Domain Health REST API

This API is defined to enable registrars to query the abuse data held by Nominet, provided by various feeds.

Using the REST API tool

• You will need to generate a key for the Nominet Domain Health REST API
• 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
• REST queries are done through a URL. For the REST API tool the URL is https://domainhealth-api.nominet.uk/rest/domainhealth
• The API will only return data for .uk domains

Generate Your API Keys

• Log into Online Services: https://secure.nominet.org.uk/auth/login.html.
•  Navigate to Domain Health in the .UK Registrar menu
• Navigate to the section: Settings
• To generate API Keys click ‘Generate new API key’
• Keys will be generated. Make a note of these, as you can only view them when you generate them

Using the REST API tool

You can use the REST API tool to:

• Find all domains
• Find by single domain
• Find domains by tag
• Find domains by abuse category

You will be able to perform the above operations on any data belonging to your account.

Additionally there are optional query parameters to tailor the response.

1. Page – If present will return the page of data requested (if possible)
2. pageSize – If present defines the amount of data in a page

Authentication

Each request should contain the Authorization HTTP header with “Basic” authentication specified. The authentication data should be formatted as follows:

accountId:apiKey

The accountId is your Nominet account number, and the apiKey is generated on the settings page of the Domain Health section within Online Services.

As per convention, the authorization data should be base64 encoded. For example:

12345678:DcyLAvihlEqvWjFUzOLJIKWkX encodes to MTIzNDU2Nzg6RGN5TEF2aWhsRXF2V2pGVXpPTEpJS1drWA==

The Authorization HTTP header would therefore be set as follows:

Authorization: Basic MTIzNDU2Nzg6RGN5TEF2aWhsRXF2V2pGVXpPTEpJS1drWA==

If your REST client supports username and password-based authentication, the accountId serves as the username and the apiKey as the password.

Operations

Find all domains

This will return all the domains for the given tag.

Request:

GET https://domainhealth-api.nominet.uk/rest/domainhealth/domains

Response:

The response will be a list of objects representing the abuse relevant for each domain.

{
“domains”: [
{
“domain”: “example.co.uk”,
“earliestReportDate”: 1337706241000,
“feedProvider”: “ANONYMOUS”,
“firstReportDate”: 1337706241000,
“host”: “example.co.uk”,
“latestReportDate”: 1607454691000,
“nominetAbuseCategory”: “MALWARE”,
“reportCount”: 4,
“sourceIdentity”: xxxxx.co.uk/yyyy”,
“tag”: “NOMINET”
},…
]
“pageNumber”: 1,
“pageSize”: 100,
“totalPages”: 1,
“totalRecords”: 53
}

Find by single domain

Request:

GET https://domainhealth-api.nominet.uk/rest/domainhealth/domains/example.co.uk

Response:

The response will be a list of objects representing the abuse relevant for each domain.

{
“domains”: [
{
“domain”: “example.co.uk”,
“earliestReportDate”: 1337706241000,
“feedProvider”: “ANONYMOUS”,
“firstReportDate”: 1337706241000,
“host”: “example.co.uk”,
“latestReportDate”: 1607454691000,
“nominetAbuseCategory”: “MALWARE”,
“reportCount”: 4,
“sourceIdentity”: “http://xxxxx.co.uk”,
“tag”: “NOMINET”
},…
]
“pageNumber”: 1,
“pageSize”: 100,
“totalPages”: 1,
“totalRecords”: 1
}

Example Request with optional query parameters

GET https://domainhealth-api.nominet.uk/rest/domainhealth/domains?page=3&pageSize=10

This would return rows 21 to 30 from the entire result set (if there were 30 or more results).

Find domains by tag

Request:

GET https://domainhealth-api.nominet.uk/rest/domainhealth/domains/tag/<tag-name>

Response:

The response will be a list of objects representing the abuse relevant for each domain within the specified tag.

{
“domains” : [
{
“domain”: “example.co.uk”,
“earliestReportDate”: 1337706241000,
“feedProvider”: “ANONYMOUS”,
“firstReportDate”: 1337706241000,
“host”: “example.co.uk”,
“latestReportDate”: 1607454691000,
“nominetAbuseCategory”: “MALWARE”,
“reportCount”: 4,
“sourceIdentity”: “https://xxxxx.co.uk”,
“tag”: “NOMINET”
},…
]
“pageNumber”: 1,
“pageSize”: 100,
“totalPages”: 1,
“totalRecords”: 53
}

Find domains by abuse category

Request:

GET https://domainhealth-api.nominet.uk/rest/domainhealth/domains/category/<category-name>

The available categories are: “ABUSE”, “COMPROMISED”, “DGA”, “MALWARE”, “PHISING”, “SPAM”

Response:

The response will be a list of objects representing the abuse relevant for each domain where the category is that specified.

{
“domains” : [
{
“domain”: “example.co.uk”,
“earliestReportDate”: 1337706241000,
“feedProvider”: “ANONYMOUS”,
“firstReportDate”: 1337706241000,
“host”: “example.co.uk”,
“latestReportDate”: 1607454691000,
“nominetAbuseCategory”: “MALWARE”,
“reportCount”: 4,
“sourceIdentity”: “https://xxxxx.co.uk”,
“tag”: “NOMINET”
},…
]
“pageNumber”: 3,
“pageSize”: 1,
“totalPages”: 53,
“totalRecords”: 53
}