Monitoring System API Specification
Overview
Monitoring System API (MoSAPI) is a REST API that allows registry operators to retrieve information collected by the SLA Monitoring (SLAM) system. The Service Level Agreement Monitoring (SLAM) system is a tool managed by ICANN to measure in near real-time the Service Level Agreements (SLA) defined in Specification 10 of the Base gTLD Registry Agreement.
The MoSAPI includes the ability to:
- Monitor the state of a TLD.
- Monitor the alarm status of a service.
- Monitor the availability of a service.
- Monitor the state of a particular incident.
- Monitor the false positive flag of an incident.
- Query a list of incidents for a service.
- Query the list of measurements for an incident.
- Query the details of a particular measurement.
- Retrieve Domain Abuse Activity Reporting (DAAR) information.
The MoSAPI also provides information on alerts and the health of the services to Registry Operators that can be used for troubleshooting purposes.
The MoSAPI is available to both gTLDs and ccTLDs.
Results for ccTLDs are logged in SLAM and ccTLD operators may opt in to MoSAPI, however no alerts or actions are triggered when a failure is detected on those services.
Get access to the MoSAPI
gTLDs
You can access the MoSAPI from the IP addresses that you have allowed for accessing the Registry Reporting Interface (RRI) with your RRI credentials if using HTTP Basic Authentication. The RRI credentials and the IP addresses allowed for accessing the RRI are managed through the Naming Services portal. If you have not already done so, you will need to provide both the IPv6 and IPv4 prefixes that you will use to connect to the MoSAPI for allowing access, via the TLDs tab on the Naming Services portal.
More information about the Naming Services portal may be found in the "Naming Services portal" section in the Registry Resources page.
ccTLDs
To request access to the MoSAPI, please contact the ICANN Global Support identifying the ccTLD for which you are requesting access. ICANN will contact the administrative and technical contacts of the ccTLD as listed in the IANA Root Database to validate the information and provide access.
TLS Client Authentication
This method uses TLS with client authentication, meaning that the MoSAPI will authenticate the client using X.509 certificates in HTTPS. TLSA DNS resource records (see RFC 6698) are used to provide a mechanism to link the client certificate to be used.
In order to setup TLS Client Authentication, the Registry Operator (logged with an account allowed to make changes for a TLD) needs to provide two pieces of information in the NSP portal:
- Domain name for TLS Client access (e.g., rsp1.nic.example)
- Authorized roles related to the MoSAPI (more than one role may be linked with a given domain name):
- MoSAPI - TLD SLAM Data
- MoSAPI - TLD DAAR Data
More technical information about TLS Client Authentication and an example of how to generate the required Resource Records and certificates for activating TLS Client Authentication may be found here: https://www.icann.org/rri.
MoSAPI OT&E Environment
ICANN currently hosts an Operational Test and Evaluation (OT&E) environment of MoSAPI exclusively for end-user testing by ICANN's contracted parties. This environment can be used to gain familiarity with the available interfaces, as well as to test system integration with MoSAPI.
You can access the MoSAPI OT&E from the IP addresses that you have allowed for accessing the Registry Reporting Interface (RRI) OT&E with your RRI OT&E credentials if using HTTP Basic Authentication.
The MoSAPI OT&E may also be accessed using TLS Client Authentication data by contacting the ICANN Global Support.
The MoSAPI OT&E provides the following functionality:
- MoSAPI - TLD SLAM Data. Access monitoring data captured by the SLA Monitoring (SLAM) system. Please see section 5 of the MoSAPI specification.
- MoSAPI - TLD DAAR Data. Access Domain Abuse Activity Reporting (DAAR) data for the TLD. Please see section 9 of the MoSAPI specification.
The URL of the MoSAPI OT&E is: https://mosapi-ote.icann.org
Specification
Current version:
Previous versions:
- ICANN Monitoring System API (MoSAPI) – Published 29 June 2020 [PDF, 647 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 30 May 2019 [PDF, 512 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 25 March 2019 [PDF, 486 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 22 February 2019 [PDF, 267 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 26 November 2018 [PDF, 573 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 02 October 2018 [PDF, 433 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 06 March 2018 [PDF, 276 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 12 February 2018 [PDF, 275 KB]
- ICANN Monitoring System API (MoSAPI) – Updated 28 November 2017 [PDF, 587 KB]