.. _REST API: REST API ======== The REST API provides registrars with simplified programmatic access to certain read-only data which may be useful for systems which do not require the full SRS/EPP protocol stack. Currently there are two registrar services available through the REST API. These are 'availability' and 'droplist'. Availability can be used to find the status code of a domain name or a list of domain names. Droplist returns a list of domains which are approaching the end of their 90-day pending release period. ACLs ---- The REST API is restricted by IP address, so registrars will need to provide InternetNZ with the IP addresses from which they will be calling the API. Please email your ACL requests to registry@internetnz.net.nz GET availability ---------------- Returns the domain availability and status code from the registry for domains specified in domain parameters. Resource URLs ~~~~~~~~~~~~~ ====================== ========= Environment URL ====================== ========= Production https://avail.prod.srs.net.nz/1.0/availability Test (OTE) https://avail.test.srs.net.nz/1.0/availability RPS https://avail.rps.srs.net.nz/1.0/availability ====================== ========= Parameters ~~~~~~~~~~ ====================== ========= Parameter Details ====================== ========= string A single string to be looked up across all 2LDs. domains[] One or more domains to be checked for availability. ====================== ========= Parameter usage: :: string=internetnz-example-domain :: domains[]=internetnz-example-domain.co.nz&domains[]=internetnz-example-domain.net.nz Response details ~~~~~~~~~~~~~~~~ ====================== ========= Key Data ====================== ========= status Alphanumeric human readable string explaining the status code as per the :ref:`Whois Protocol`. code Numeric status code as per the :ref:`Whois Protocol`. domain The domain name as stored in the register. Generally this will be the same as the domain name which was queried (from the query string). In the case of queries for domain names containing non-ASCII characters, it will be the encoded domain name stored in the register, formatted according to RFC 3492. original If the domain has an IDN, this field will contain the domain name in the script intended by the registrant, encoded in UTF-8. ====================== ========= HTTP Headers ~~~~~~~~~~~~ Server-to-Client ============================ ================== ========== Header Value Comments ============================ ================== ========== Content-Type application/json Standard Content-Type header for JSON. Access-Control-Allow-Origin \* Send a Cross-Origin Resource Sharing (CORS) header. ============================ ================== ========== Examples ~~~~~~~~ Request: :: GET /1.0/availability?string=internetnz-example-domain HTTP/1.1 Response: .. code-block:: json [ { "code": "220", "domain": "internetnz-example-domain.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.ac.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.co.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.cri.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.geek.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.gen.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.health.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.iwi.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.kiwi.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.maori.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.mil.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.net.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.org.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.school.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.govt.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.parliament.nz", "status": "Available" } ] Request: :: GET /1.0/availability?domains[]=internetnz-example-domain.co.nz&domains[]=internetnz-example-domain.net.nz&domains[]=internetnz-example-domain.kiwi.nz HTTP/1.1 Response: .. code-block:: json [ { "code": "220", "domain": "internetnz-example-domain.co.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.net.nz", "status": "Available" }, { "code": "220", "domain": "internetnz-example-domain.kiwi.nz", "status": "Available" } ] .. _droplist: GET droplist ------------ Provides registrars with access to the list of domains which are approximately two days from the end of their 90-day PendingRelease period and the associated date they are likely to be released. Resource URLs ~~~~~~~~~~~~~ ====================== ========= Environment URL ====================== ========= Production https://avail.prod.srs.net.nz/1.0/droplist Test (OTE) https://avail.test.srs.net.nz/1.0/droplist RPS https://avail.rps.srs.net.nz/1.0/droplist ====================== ========= Response details ~~~~~~~~~~~~~~~~ ====================== ========= Key Data ====================== ========= registered The date the domain was registered. Timestamp with time zone cancel_date The date the domain was cancelled (deleted). Timestamp with time zone release_date The date the domain is available to be released, this is 90 days from the cancellation date. Timestamp with time zone domain The domain name as stored in the register. drop_date The date that the domain is expected to be released by the registry via the release domains scheduled job. ====================== ========= .. note:: All domains that have a release date less than the schedule_date are expected to be released by the release domains job. Names released by the released domains job will be available for registration at the end of the maintenance window the job runs in. The maintenance window ends at 00:00:34 HTTP Headers ~~~~~~~~~~~~ Server-to-Client ============================ ================== ========== Header Value Comments ============================ ================== ========== Content-Type application/json Standard Content-Type header for JSON. Last-Modified "HTTP-date" format The last modified date for the requested object (in "HTTP-date" format as defined by `RFC 7231 `_) ============================ ================== ========== Request: :: GET /1.0/droplist HTTP/1.1 Response: .. code-block:: json [ { "cancel_date": "2014-07-11 09:23:38+12:00", "domain": "internetnz-drop-domain.net.nz", "drop_date": "2014-10-10 00:30:00+13:00", "registered": "2007-03-26 19:49:33+12:00", "release_date": "2014-10-09 09:23:38+13:00" }, { "cancel_date": "2014-07-12 23:35:00+12:00", "domain": "internetnz-drop-domain2.co.nz", "drop_date": "2014-10-11 00:30:00+13:00", "registered": "2011-07-12 18:25:41+12:00", "release_date": "2014-10-10 23:35:00+13:00" }, { "cancel_date": "2014-07-11 07:45:05+12:00", "domain": "internetnz-drop-domain3.nz", "drop_date": "2014-10-10 00:30:00+13:00", "registered": "2013-06-04 23:13:23+12:00", "release_date": "2014-10-09 07:45:05+13:00" } ]