2021-09-02 Revision: 2.1
- Introduction
- About this Document
- The .dk Registry in Brief
- Domain Availability Service
- Available Environments
- Implementation Limitations
- Domain Status
- Service
/domain/is_available - Test Data
- References
- Resources
- Mailing list
- Issue Reporting
- Additional Information
- Demo Client
- Appendices
- HTTP Status Codes
This document describes and specifies the implementation offered by DK Hostmaster A/S for interaction with the central registry for the ccTLD dk using the Domain Availability Service (DAS). It is primarily aimed at a technical audience, and the reader is required to have prior knowledge of HTTP and possibly DNS registration.
This specification describes version 1 (1.X.X) and 2 (2.X.X) of the DK Hostmaster DAS Implementation. Future releases will be reflected in updates to this specification, please see the document history section below. The document describes the current DK Hostmaster DAS implementation, for more general documentation on the used protocols and additional information please refer to the RFCs and additional resources in the References and Resources chapters below. Any future extensions and possible additions and changes to the implementation are not within the scope of this document and will not be discussed or mentioned throughout this document.
A printable version can be obtained via this link, using the gitprint service.
Do note that all the examples are constructed and the access credentials are examples and are non-functional.
This document is copyright by DK Hostmaster A/S and is licensed under the MIT License, please see the separate LICENSE file for details.
-
2.1 2021-09-02
- Updated support information
-
2.0 2021-09-02
- Service updated to version 2.0.0, specification following service, no protocol changes only implementation changes
-
1.15 2019-03-28
- Added information on IP address whitelisting to section on
- Added information on IP address whitelisting to section on Environments
-
1.14 2018-11-30
- Sandbox accounts and credentials are no longer supported and has been removed
- Information on the consolidated sandbox environment has been added
-
1.13 2018-11-22
- Minor correction to listing of enumerated values for responses
-
1.12 2018-11-21
- Minor correction to the Test Data section
-
1.11 2018-11-16
- Corrected the examples so these are directly executable
-
1.10 2018-10-31
- Updated the Test Data section. Example data for the deprecated
blockedremoved andenquededadded
- Updated the Test Data section. Example data for the deprecated
-
1.9 2018-10-26
- Clarified the endpoint URLs
-
1.8 2018-08-22
- Added information on status
enqueued, introduced with server version 1.4.0
- Added information on status
-
1.7 2017-12-19
- Removed information on status
blocked, which has been deprecated
- Removed information on status
-
1.6 2016-10-18
- Added information on new status
available-on-waiting-list
- Added information on new status
-
1.5 2016-09-01
- Minor clarification on credentials
-
1.4 2016-06-09
- Removed obsolete data sheet
-
1.3 2016-06-09
- Added link to demo client, also available on GitHub
-
1.2 2016-04-19
- Filled in data in the data sheet, more information will follow
- Filled in details on blocking policy for failed login attempts based on user-id and IP-address
- Added link to the gitprint service
-
1.1 2015-09-02
- Migrated to markdown and hosting on GitHub, no changes to actual content just formatting
-
1.0 2013-02-25
- Initial revision
DK Hostmaster is the registry for the ccTLD for Denmark (dk). The current model used in Denmark is based on a sole registry, with DK Hostmaster maintaining the central DNS registry. The service is not subject to any sorts of standards but adheres to best practices in the implementation of REST and use of HTTP in context of REST.
The DK Hostmaster’s DAS is based on a SOA architecture. The implementation is regarded as a service offered to external parties requiring inquiry actions towards the DK Hostmaster registry.
DAS is an HTTP-based protocol aimed at providing a speedy interface for requesting information from the DK Hostmaster registry. The service is intended for machine-to-machine communication in a client-server setup. Please see the References chapter for more information on specifications and references for HTTP and related.
The service requires the use and possible development of client software. This is beyond the scope of this specification as the API and other assets for assisting in this are the primary object of this document.
In addition to the assets, DK Hostmaster aims to assist users and developers of possible client software with integration towards DK Hostmaster and therefore provide facilities to ease this integration. This is primarily centered around a sandbox environment and related documentation.
DK Hostmaster offers the following environments:
| Environment | Role | Policies |
|---|---|---|
| production | production | This environment will be the production environment for the DK Hostmaster Domain Availability Service |
| sandbox | development | This environment is intended for client development towards the DK Hostmaster Domain Availability Service. |
Do note that accessing the service does not require IP address whitelisting with DK Hostmaster prior to use.
- is_available requests made to this environment will reflect live production data
- production credentials and proper authorization are needed to access the service
Production is available at: https://das.dk-hostmaster.dk/
- is_available requests made to this environment will reflect data only available in the isolated [sandbox environment], please see the sandbox environment specification for details.
- Please see the section on Test Data.
Sandbox is available at: https://das-sandbox.dk-hostmaster.dk/
In general the service is not localized and all DAS related errors and messages are provided in English.
The only localization support provided by the service is the support for IDN domains. Please note the service require requests in UTF-8, meaning punycode encoded domain names will be interpreted as-is, meaning in ASCII context.
The punycode encoded example of: xn--kdplg-orai3l.dk will be evaluated as xn--kdplg-orai3l.dk and not decoded to kødpålæg.dk prior to evaluation.
This service is called using Basic HTTP Authentication supporting current authentication credentials, consisting of:
- user-id / handle
- password
Too many failed login attempts will block the account. The block for a user-id lasts for 24 hours and it automatically lifted.
If failing login attempts continue or is spread across user-ids originating from the same IP-address the IP-address will be blocked. The block for an IP-address lasts for 24 hours and it automatically lifted.
The service supports JSON, XML and plain text format, using the UTF-8 character set. In order to specify what format you want to retrieve the format should be specified in the HTTP header: Accept-header. Control the content type by setting header info, using the below examples:
Accept: application/json; charset=utf-8Accept: application/xml; charset=utf-8Accept: text/plain; charset=utf-8
If the content type is not specified, the response will reflect this with an HTTP status code: 415 (see: HTTP status code listing in appendices).
We only allow a certain number of requests per minute. We reserve the right to adjust the rate limit in order to provide a high quality of service.
If rate limit is exceeded the HTTP status code 429 “Too many requests” is returned. Further, the response will have a Retry-After header that tells you for how many seconds to wait before retrying.
Current limit is set to 60 requests per minute.
Please note the sandbox environment does not enforce rate limiting at this time, due to a wish for unlimited use for developers.
The service uses a basic session handling based on cookies.
| Parameter | Value | Description |
|---|---|---|
| cookie name | dkhm-das-session | This is the name of the cookie |
| cookie domain | .dk-hostmaster.dk | |
| expiration | 3600 seconds | The expiration date provided in the cookie is in the GMT timezone |
The service returns a queried domain name and it's status if possible. The different domain status has the following meanings:
A given domain name is available for application.
A given domain name is in use and is not available for application.
A given domain name has been offered to the first entry on a waiting list and is awaiting the specific user's approval or decline to this offer.
If an application has been enqueued with DK Hostmaster, but not processed. This can last a few seconds to a few days if the application require accept of agreement from the designated registrant
Method:
GET
URL path:
/domain/is_available/<domain>
| Parameter | Type | Description | Mandatory | Example |
|---|---|---|---|---|
| domain | string | The domain name to evaluate, it has to adhere to the domain name format expected by DK Hostmaster, see References. | yes | abc.dk, jordbærgrød.dk |
| status | enumerated string | string indicating the status of the request, either one of: available, unavailable, enqueued or available-on-waiting-list |
yes | |
| message | enumerated string | string providing a human-readable message, “OK” on success | optional |
Default HTTP header observed: 200 OK. Additional status data in Status and Message. For additional HTTP status codes, which can be exhibited by the service, please refer to the addendum.
JSON:
% curl --header Accept:application/json \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/dk-hostmaster.dk{"domain":"dk-hostmaster.dk","domain_status":"unavailable","message":"OK","status":200}XML:
% curl --header Accept:application/xml \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/dk-hostmaster.dk<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<response>
<domain>dk-hostmaster.dk</domain>
<domain_status>unavailable</domain_status>
<message>OK</message>
<status>200</status>
</response>Text:
% curl --header Accept:text/plain \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/dk-hostmaster.dkdomain_status:unavailable
status:200
message:OK
domain:dk-hostmaster.dk
JSON:
% curl --header Accept:application/json \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/asdf.dk{"domain":"asdf.dk","domain_status":"available","message":"OK","status":200}XML:
% curl --header Accept:application/xml \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/asdf.dk<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<response>
<domain>asdf.dk</domain>
<domain_status>available</domain_status>
<message>OK</message>
<status>200</status>
</response>Text:
% curl --header Accept:text/plain \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/asdf.dkdomain:asdf.dk
message:OK
status:200
domain_status:available
Please note the -v flag to curl and that the response has been stripped down.
Text:
% curl -v --header Accept:text/plain \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/asdfdomain:asdf
status:400
message:Invalid domain syntax
Please note the -v flag to curl and that the response has been stripped down.
Text:
% curl -v --header Accept:text/plain \
https://REG-123456:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/asdfmessage:Forbidden
status:403
The sandbox uses a predefined set of test data. All domains not listed in the below list will be reported as available in the sandbox environment.
| Domain name | Status | Notes |
|---|---|---|
dk-hostmaster.dk |
unavailable |
The domain is active |
waiting-list.dk |
available-on-waiting-list |
The domain status is awaiting a specific registrant |
enqueued.dk |
enqueued |
The domain application status is enqueued |
æøåöäüé.dk |
unavailable |
This domain is active |
| * | * | Depending on what domains has been registered with the sandbox environment (see states above), if not registered available will be returned. Please see the sandbox environment specification for details. |
To use the DAS sandbox you have to use your own account, please see the sandbox environment specification for details.
Here is a list of documents and references used in this document
- General Terms and Conditions
- RFC: 2616 Hypertext Transfer Protocol -- HTTP/1.1
- RFC: 2617 HTTP Authentication: Basic and Digest Access Authentication
- Documentation on the format of a domain name with the DK Hostmaster A/S registry
Resources for DK Hostmaster DAS support are listed below.
DK Hostmaster operates a mailing list for discussion and inquiries about the DK Hostmaster DAS implementation. To subscribe to this list, write to the address below and follow the instructions. Please note that the list is for technical discussion only, any issues beyond the technical scope will not be responded to, please send these to the contact issue reporting address below and they will be passed on to the appropriate entities within DK Hostmaster A/S.
tech-discuss+subscribe@liste.dk-hostmaster.dk
For issue reporting related to this specification, the DAS implementation or sandbox or production environments, please contact us. You are of course welcome to post these to the mailing list mentioned above, otherwise, use the regular support channels.
The DK Hostmaster website:
https://www.dk-hostmaster.dk/en/das
A demo client is available as open source under a MIT license.
| Status code | Message | Description |
|---|---|---|
| 200 | OK | Service returned a valid response |
| 400 | Bad request | The request could not be fulfilled due to missing parameters or malformed syntax |
| 401 | Unauthorized | Authentication failed |
| 403 | Forbidden | Not authorized |
| 404 | Page not found | The request assumes a service (URL) not provided or unsupported at this time |
| 415 | Unsupported Media Type | The requested media type is unsupported, see section on Media Types |
| 429 | Too many attempts | Rate limiting triggered, please see section on Rate Limiting |
| 500 | Server Error | Service malfunction |
| 503 | Service Unavailable | Maintenance mode |
Please see the Wikipedia; List of HTTP status codes.