REST API

A REST based API function exists to replace the list functionality that was previously offered by the Automaton. Registrars can generate an API key in the Online Services, under Tag Settings.

Using the REST List API tool

• Generate an API key from the Tag Settings page in Online Services. (See List API section)
• You will most likely need some form of REST client to talk to the API, although it is possible to do this via your web browser. Many modern web browsers offer REST Apps/plugins. 
• Unlike SOAP queries, REST queries are done through a URL. For the REST API list tool the URL is https://restapi.nominet.org.uk/rest<query_here>
• An 'Authorization' token is required which is a Base 64 encoded string containing the tag and the key generated previously, separated by a colon. For example, the String for the NOMINET tag would be something like:
  • NOMINET:DcyLAvihlEqvWjFUzOLJIKWkX
• This must then be encoded in Base64 encoding (which is standard for REST authorisations) and will look something like:

    Tk9NSU5FVDpEY3lMQXZpaGxFcXZXakZVek9MSklLV2tY

• There are numerous encoders available online for generating Authorization strings.
• Finally, the Authorization HTTP header must be set, and should be as follows:

Authorization: Basic Tk9NSU5FVDpEY3lMQXZpaGxFcXZXakZVek9MSklLV2tY

Methods

The following queries are available to use within the REST API.

All domains

/domains/all

Returns JSON containing domains on a tag in order of the domain key and suffix. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record.

Domains Expiry After Date

/domains/expiry/after/{date}

Returns JSON containing domains that expire after a specified date. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record. 

The date should be supplied in the URL in the format of dd-MMM-yyyy e.g. 16-May-2018

Domains Expiry Before Date

/domains/expiry/before/{date}

Returns JSON containing domains that expire before a specified date. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record. 

The date should be supplied in the URL in the format of dd-MMM-yyyy e.g. 16-May-2018

Domains Expiry Within Range

/domains/expiry/range/{from}/{to}

Returns JSON containing domains that expire within a specified date range. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record. 

The date should be supplied in the URL in the format of dd-MMM-yyyy e.g. 16-May-2018

Domains Created After Date

/domains/created/after/{date}

Returns JSON containing domains that were created after a specified date. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record. 

The date should be supplied in the URL in the format of dd-MMM-yyyy e.g. 16-May-2018

Domains Created Before Date

/domains/created/before/{date}

Returns JSON containing domains that were created before a specified date. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record. 

The date should be supplied in the URL in the format of dd-MMM-yyyy e.g. 16-May-2018

Domains Created Within Range

/domains/created/range/{from}/{to}

Returns JSON containing domains that were created within a specified date range. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record. 

The date should be supplied in the URL in the format of dd-MMM-yyyy e.g. 16-May-2018

Domains with Registrant ID

/domains/registrant/{registrantID}

Returns JSON containing domains that are associated with a given registrant ID. The JSON contains the domain ID, the creation date, the full domain name, the expiry date, the registrant ID and the registrant EPP ID for each domain record. 

Domains with Registrant EPP ID

/domains/epp/{eppID}

Returns JSON containing domains that are associated with a given registrant EPP ID.

All Contacts on Tag

/contacts/all

Returns JSON containing all contacts assigned to a given Tag that are associated with a domain. The JSON contains the Contact ID (Registrant ID), registrant EPP ID, Name, Email, Organisation name, Address (street 1, street 2, street 3, city, country, postcode, phone), Trading name, Org type, Date created.

Contacts with ID

/contacts/registrant/{registrantID}

Returns JSON containing all contacts assigned to a given Tag that are associated with a domain with a given ID. The JSON contains the Contact ID (Registrant ID), registrant EPP ID, Name, Email, Organisation name, Address (street 1, street 2, street 3, city, country, postcode, phone), Trading name, Org type, Date created.

Contacts with EPP ID

/contacts/epp/{registrantEppID}

Returns JSON containing all contacts assigned to a given Tag that are associated with a domain with a given EPP ID. The JSON contains the Contact ID (Registrant ID), registrant EPP ID, Name, Email, Organisation name, Address (street 1, street 2, street 3, city, country, postcode, phone), Trading name, Org type, Date created.

Contacts with Name

/contacts/name/{name}

Returns JSON containing all contacts assigned to a given Tag that are associated with a domain with a given contact name. The JSON contains the Contact ID (Registrant ID), registrant EPP ID, Name, Email, Organisation name, Address (street 1, street 2, street 3, city, country, postcode, phone), Trading name, Org type, Date created.

Contacts with email

/contacts/email/{email}

Returns JSON containing all contacts assigned to a given Tag that are associated with a domain with a given email address. The JSON contains the Contact ID (Registrant ID), registrant EPP ID, Name, Email, Organisation name, Address (street 1, street 2, street 3, city, country, postcode, phone), Trading name, Org type, Date created.

Additional Optional Parameters

Each query will also return some supplementary information, namely the current page number, the current page size, the total number of records and the total number of pages. 

There are 2 optional parameters that the user can set that can impact their result set. 

Page Size

pageSize={size}

This allows the user to specify the number of records returned. The maximum page size is 10,000. This is also the default size.

Page Number

page={pageNumber}

This allows the user to specify the current page. The default is 1.