Domain Availability Service (DAS) Specification
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.editorconfig
.markdownlint.json
LICENSE
README.md

README.md

DK Hostmaster Logo

DK Hostmaster Domain Availability Service Specification

2018-11-30 Revision: 1.14

Table of Contents

Introduction

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.

About this Document

This specification describes version 1 (1.0.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.

License

This document is copyright by DK Hostmaster A/S and is licensed under the MIT License, please see the separate LICENSE file for details.

Document History

  • 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

  • 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 blocked removed and enqueded added
  • 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
  • 1.7 2017-12-19

    • Removed information on status blocked, which has been deprecated
  • 1.6 2016-10-18

    • Added information on new status available-on-waiting-list
  • 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

The .dk Registry in Brief

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.

Domain Availability Service

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.

Available Environments

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.

Production Environment

  • 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/

Sandbox Environment

  • 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/

Implementation Limitations

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.

AAA

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.

Supported Media-types

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-8
  • Accept: application/xml; charset=utf-8
  • Accept: 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).

Rate Limiting

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.

Session Handling

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

Domain Status

The service returns a queried domain name and it's status if possible. The different domain status has the following meanings:

Available: available

A given domain name is available for application.

Unavailable: unavailable

A given domain name is in use and is not available for application.

Available for designated user from waiting list: available-on-waiting-list

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.

Enqueued: enqueued

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

Service /domain/is_available

Request

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.

Examples for unavailable domain

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.dk
domain_status:unavailable
status:200
message:OK
domain:dk-hostmaster.dk

Examples for available domain

JSON:

% curl --header Accept:application/json \
https://REG-999999:secret@das-sandbox.dk-hostmaster.dk/domain/is_available/adsf.dk
{"domain":"adsf.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.dk
domain:asdf.dk
message:OK
status:200
domain_status:available

Example with bad domain parameter

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/asdf
domain:asdf
status:400
message:Invalid domain syntax

Example with bad credentials

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/asdf
message:Forbidden
status:403

Test Data

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.

Domains

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.

Accounts / Credentials

To use the DAS sandbox you have to use your own account, please see the sandbox environment specification for details.

References

Here is a list of documents and references used in this document

Resources

Resources for DK Hostmaster DAS support are listed below.

Mailing list

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

Issue Reporting

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 address specified below:

  • info@dk-hostmaster.dk

Additional Information

The DK Hostmaster website:

  • https://www.dk-hostmaster.dk/en/das

Demo Client

A demo client is available as open source under a MIT license.

Appendices

HTTP Status Codes

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