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 NZRS with the IP addresses from which they will be calling the API.

Please email your ACL requests to support@nzrs.net.nz

GET availability

Returns the domain availability and status code from the registry for domains specified in domain parameters.

Resource URLs

Environment URL
SRS Production https://prod.srs.net.nz/1.0/availability
SRS RPS/Pre-production https://rps.srs.net.nz/1.0/availability
SRS Test/OTE https://test.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=nzrs-example-domain
domains[]=nzrs-example-domain.co.nz&domains[]=nzrs-example-domain.net.nz

Response details

Key Data
status Alphanumeric human readable string explaining the status code as per the Whois Protocol.
code Numeric status code as per the 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=nzrs-example-domain HTTP/1.1

Response:

[
    {
        "code": "220",
        "domain": "nzrs-example-domain.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.ac.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.co.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.cri.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.geek.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.gen.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.health.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.iwi.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.kiwi.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.maori.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.mil.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.net.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.org.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.school.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.govt.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.parliament.nz",
        "status": "Available"
    }
]

Request:

GET /1.0/availability?domains[]=nzrs-example-domain.co.nz&domains[]=nzrs-example-domain.net.nz&domains[]=nzrs-example-domain.kiwi.nz HTTP/1.1

Response:

[
    {
        "code": "220",
        "domain": "nzrs-example-domain.co.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.net.nz",
        "status": "Available"
    },
    {
        "code": "220",
        "domain": "nzrs-example-domain.kiwi.nz",
        "status": "Available"
    }
]

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
SRS Production https://prod.srs.net.nz/1.0/droplist
SRS RPS/Pre-production https://rps.srs.net.nz/1.0/droplist
SRS Test/OTE https://test.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:

[
    {
        "cancel_date": "2014-07-11 09:23:38+12:00",
        "domain": "nzrs-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": "nzrs-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": "nzrs-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"
    }
]