ICANN Monitoring System API (MoSAPI) Version 2.11.2 2020-06-29 1. Introduction ....................................................................................................................................... 4 1.1. Date and Time .......................................................................................................................... 4 1.2. Credentials ................................................................................................................................ 4 1.3. Glossary ...................................................................................................................................... 4 1.4. Technical requirements ....................................................................................................... 5 2. Common elements used in this specification ....................................................................... 6 3. Session handling ............................................................................................................................... 7 3.1. Creating a session ................................................................................................................... 7 3.2. Closing a session ..................................................................................................................... 9 4. API endpoint authentication .................................................................................................... 10 5. gTLD Base Registry Agreement - Specification 10 monitoring ................................. 11 5.1. Monitoring the state of a TLD ........................................................................................ 11 5.2. Monitoring the Alarm status of a Service .................................................................. 14 5.3. Monitoring the availability of a Service ..................................................................... 15 5.4. Query a list of Incidents for a Service ......................................................................... 16 5.5. Monitoring the state of a particular Incident .......................................................... 18 5.6. Monitoring the False Positive flag of an Incident .................................................. 19 5.7. Querying the list of measurements for an Incident .............................................. 21 5.8. Querying the details of a particular measurement ............................................... 22 5.8.1. DNS/DNSSEC Monitoring error codes .................................................................. 28 5.8.2. RDDS Monitoring error codes ................................................................................... 33 6. Maintenance window support ................................................................................................. 37 6.1. Common elements for maintenance window support ........................................ 37 6.1.1. Schedule object ................................................................................................................ 37 6.1.2. Schedule object identifier ........................................................................................... 37 6.2. Creating or updating a schedule for a maintenance window ........................... 38 6.3. Deleting a schedule for a maintenance window .................................................... 39 6.4. Retrieving a schedule object for a maintenance window .................................. 40 6.5. Getting the list of maintenance windows that have not ended yet ................ 41 7. Probe node network .................................................................................................................... 42 8. HTTP/400 extended error codes ........................................................................................... 44 9. Domain Abuse Activity Reporting (DAAR) ........................................................................ 46 9.1. Getting the latest DAAR report available for the TLD ......................................... 46 9.2. Querying for a DAAR report for a date ....................................................................... 48 9.3. Querying for DAAR reports available ......................................................................... 49 10. Recent Measurements ............................................................................................................ 51 1 10.1. Querying years for which reports are available ..................................................... 51 10.2. Querying months for which reports are available ................................................ 52 10.3. Querying days for which reports are available ...................................................... 53 10.4. Querying for available measurements ....................................................................... 54 10.5. Querying the details of a particular measurement ............................................... 55 11. List of ICANN-accredited Registrars’ RDAP Base URLs ........................................... 56 12. Alternative methods of authentication ........................................................................... 58 12.1. Overview ................................................................................................................................. 58 12.2. TLS Client Authentication ................................................................................................ 58 12.3. Authentication and Authorization with TLS Client Authentication .............. 59 2 Document Revision History Projected date to Publishing implement the version Version Description of the change date of the specification in production 2.5 2017/11/28 First version released to the public. In production ADDITION - Default rate-limit and expiration date values were added in section 3.1. ADDITION - Maximum length definitions for name and description were added in section 6.1.1. 2.6 2018/02/12 In production ADDITION - Result code 2016 (section 8) was added to the result code table. CHANGE - Result code 2007 message (section 8) was changed to cover the case of equal values in the endTime and startTime. 2.7 2018/03/06 MoSAPI released as a production In production service. 2.8 2018/10/02 ADDITION - UP-inconclusive-no-data Never released to and UP-inconclusive-no-probes were production, replaced added to sections 5.1 and 5.8. with version 2.8.1 CHANGE - Error codes changed in sections 5.8.1 and 5.8.2. CHANGE - Editorial updates. 2.8.1 2018/11/26 CHANGE - Minor adjustments to the list Never released to of error codes in sections 5.8.1 and production, replaced 5.8.2. with version 2.8.2 2.8.2 2019/02/21 CHANGE - Error codes changed in 2019/02/21 sections 5.8.1. 2.9 2019/03/25 ADDITION - Section 9 and 10 were 2019/04/30 added. 2.10 2019/05/30 ADDITION – Section 11. 2019/05/30 CHANGE – Editorial updates. 2.11 2020/01/31 ADDITION – Section 12. Never released to CHANGE – Editorial updates. production, replaced with version 2.11.1 2.11.1 2020/02/26 ADDITION – Additional details in Never released to Section 12. production, replaced CHANGE – Rate-limit in Section 3.1. with version 2.11.2 ADDITION – Section 1.4. 2.11.2 2020/06/29 ADDITION – Additional details in July 2020 Section 12. CHANGE – Response message in Section 4. CHANGE – Technical ReQuirements in Section 1.4. 3 1. Introduction This document describes the REST API endpoints provided by ICANN to contracted parties and Country Code Top-Level Domain (ccTLD) registries in order to retrieve monitoring and other information that is intended to be available only to the specific registry or registrar. 1.1. Date and Time All the fields that represent dates in this document must contain timestamps indicating the date and time in Coordinated Universal Time (UTC). 1.2. Credentials The MoSAPI uses the same credentials (e.g., username, password, list of IP address blocks - IPv4 and/or IPv6) as the Registration Reporting Interface (RRI). These credentials are managed through the NSP portal provided by ICANN to the contracted parties or through email in the case of ccTLD registries. The MoSAPI supports both IPv4 and IPv6 transport. The MoSAPI reQuires the use of Hypertext Transfer Protocol Secure (HTTPS) to provide confidentiality, server authentication, and integrity in the communication channel. 1.3. Glossary In the following section, the concepts used in the MoSAPI are explained: ● Service: a service that may be monitored by the MoSAPI. The potential monitored services are: dns, rdds, epp and dnssec. ● Test Cycle: series of tests executed to verify the state of a monitored Service. For Domain Name System (DNS), the Service is considered to be up at a particular moment, if at least two of the delegated name servers registered in the DNS have successful results from tests to each of their public-DNS registered IP addresses in the root zone for the name server. For the Registration Data Directory Services Requirements (RDDS) Services (i.e. Whois tcp/43 and web-Whois) to be considered up at a particular moment, the Services must have successful results from tests to the randomly chosen public-DNS registered IP address to which whois.nic.<TLD> resolves. If 51% or more of the testing probe nodes see a monitored Service as unavailable at a given time, the Service will be considered unavailable. For RDDS, if any of the RDDS Services (i.e. Whois tcp/43 and web-Whois) is considered unavailable, the RDDS will be considered unavailable. The minimum number of active testing probe