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 |
|
Test (OTE) |
|
RPS |
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 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=internetnz-example-domain HTTP/1.1
Response:
[
{
"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": "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"
}
]
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 |
|
Test (OTE) |
|
RPS |
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": "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"
}
]