Machine-readable Registry Maintenance Notification JSON

machine-readable-registry-maintenance-notification-json.txt

Machine-readable registry maintenance notifications through RESTful webservice on port 443 with JSON formatted response (RFC 4627):

GET https://status.registry.tld/maintenance

Arguments
  - environment     [optional] (string) 'production', 'test', 'staging' or 'all' (default: production)
  - start           [optional] (date)   according ISO 8601 YYYY-MM-DD (default: today)
  - end             [optional] (date)   according ISO 8601 YYYY-MM-DD (default: today + 3 months)
  
Example call: GET https://status.registry.tld/maintenance?environment=production&start=2017-04-01&end=2017-06-30

Response successful:
HTTP Response Code 200 (RFC 7231)
content-type: application/json
{
  "maintenance":[
    {
      "notification":{
        "system":["epp.registry.tld"],
        "environment":"production",
        "start":"2017-04-30T06:00:00+00:00",
        "reason":"planned maintenance",
        "impact":["blackout"],
        "remark":"https://portal.registry.tld/maintenance-description-foobar",
        "end":"2017-04-30T07:00:00+00:00",
        "tlds":["barfoo","foobar"],
        "intervention":"no"
      }
    },
    {
      "notification":{
        "system":["epp.registry.tld","whois.registry.tld","https://portal.registry.tld"],
        "environment":"production",
        "start":"2017-06-15T04:30:00+00:00",
        "reason":"planned maintenance",
        "impact":["partial","partial","blackout"],
        "remark":"https://portal.registry.tld/maintenance-description-foobar",
        "end":"2017-06-15T05:30:00+00:00",
        "tlds":["foobar"],
        "intervention":"yes"
       }
    }
  ]
}

Explanation of JSON response values
  - system          [required] (array)    affected maintained systems
  - environment     [required] (string)   environment of affected maintained systems
  - start           [required] (datetime) according ISO 8601 YYYY-MM-DDThh:mm:ssTZD
  - end             [required] (datetime) according ISO 8601 YYYY-MM-DDThh:mm:ssTZD
  - reason          [required] (string)   'planned maintenance' or 'emergency maintenance'
  - impact          [required] (array)    impact level per affected system; values are 'partial' or 'blackout'; order by afftected systems
  - remark          [required] (string)   URL to detailed maintenance description or empty
  - tlds            [required] (array)    affected top-level domains
  - intervention    [required] (string)   'yes' or 'no' - if yes, please specify on the website where remarks link to 

// ---------------------------------------
Response error:
HTTP Response Code 404 (RFC 7231)
content-type: application/json
{
  "maintenance":[
    {
      "notification":{
        "code":"NO_RESULT",
        "error":"No maintenance notifications found in this timeframe"
      }
    }
  ]
}

Explanation of JSON response values
  - code            [required] (string) 'NO_RESULT', 'WRONG_VALUE_ENVIRONMENT', 'WRONG_VALUE_START_DATE' or 'WRONG_VALUE_END_DATE'
  - error           [required] (string) explanation of the error code
  
Error Messages by code
  - NO_RESULT                 No maintenance notifications found in this timeframe
  - WRONG_VALUE_ENVIRONMENT   Given environment does not exist
  - WRONG_VALUE_START_DATE    Given start date does not exist or before end date
  - WRONG_VALUE_END_DATE      Given end date does not exist or before start date

I strongly advise against inventing yet another protocol just for maintenance notices.

Personally, I prefer an EPP poll queue message because I already have code that parses those. Setting up yet another endpoint somewhere means I need to add and maintain yet another system to monitor it.

But, if you insist on something you can query outside of EPP, then I would rather see you use an existing protocol, like an RSS feed or iCal message format because there already exist plenty of open-source libraries for parsing those.

@dwright: Thank you for your feedback. In my opinion neither RSS nor iCal is really suitable for that and all programming languages support parsing JSON anyway. I don't see that as an issue. EPP is a totally different story. Yes, we could propose an EPP extension, but knowing the process to achieve that, I would advise against it. It would be a rather long process and I think we rather want a quick win instead of dragging out.