Getting Started with Checkdomain API

With the all new checkdomain API, you can easily automate your domain business. Create and maintain your contact handles - manage your domain portfolio, register new domains or administer your DNS records.

This guide will help you to understand our implementation, the API design and will give you a brief overview of REST and OAuth2.

So, after reading this guide, be sure to check out the API reference.

The checkdomain API is designed for developers, engineers, or anyone else who's comfortable creating custom-coded solutions or integrating with RESTful APIs. In the near future we will also provide several clients for a couple of different programming languages.

The REST design is an integral part of our API. If you'd like to learn more about REST before using the API, check out the Introduction to REST guide.

You are also invited to share your plugin, your integration of our API or your client to connect to our API from languages we didn't provide yet. Be part of the checkdomain community.

If you do need more and detailed help, don't hesitate to contact us for further assisstence.

In the versioning of our API we decided for the most common way: the semantic versioning. Just in case you don't want to read through this specification but want to have a closer look we will explain semantic versioning in a couple of words.
Every release will have a version number from the beginning on that will look like this: 1.0.0

Important are the point-seperated parts. The first part is the major version, second is the minor version and the last part is indicating bugfixes and patches. Except the major version all minor version and patches/bugfixes won't break the compatibility with other version. That's why you only provide the major version.

MAJOR.MINOR.PATCH (2.0.0)
  • MAJOR version: we made changes that break backwards compatibility
  • MINOR version: we made changes that are important but backwards compatible
  • PATCH version: we made bugfixes that didn't infect backwards compatibility

The API is designed to always have a major version number provided within the URI allowing you to manage which version you are using. We will anounce newer versions and provide early access to the documentation. Switching to a newer major version as soon as possible is recommended but you will have a period in which both versions will be supported.

Feeling ready to start? Then let's get to the following steps:

We have a full section about testing your connection to the checkdomain API.

Please contact our experts using the following contact form to get registered for your API access. Once your account got enabled the appropriate functions for managing your API experience will appear in your customer area, upon your next log in.

For ease of use you can generate an API access token, which you have to provide with every request, in your checkdomain customer area. You can find detailed information in our "How to" about authentication.

Please take care of your checkdomain credentials and the access token at all time. Do not share or publish!

Right where you can generate and re-generate an API access token in your customer area, you can manage your IP whitelist. Just fill in your IP address (IPv4 and IPv6 allowed) and save. It may take a couple of seconds for the IP address to be published by the handling system.

SSL

There are a couple of security systems to talk about. We have a valid and signed certificate for the checkdomain API. Please make sure to only connect to our API via HTTPS. Unsecure requests via HTTP won't be recognized.

TLS 1.0 and 1.1 Deprecation

Due to further security reasons we don't support early TLS versions. Minimum version of TLS is 1.2.

We strongly encourage any developers who are using the checkdomain API to ensure that their software supports negotiating TLS 1.2 connections, and to coordinate with their system administrators to update software to take advantage of newer TLS versions. In addition, we recommend proactively switching over to TLS 1.2 when communicating with checkdomains API by modifying your API client software to enforce TLS 1.2 negotiation.

IP whitelisting

Another safety measure is the whitelisting of IP addresses you want to communicate from. This enables us to only allow connections that have been explicitly stated by you. Requests from other IP addresses will be declined by our systems. So, this is the moment to check, if you really provided all ip addresses of your server.

The checkdomain API supports 5 HTTP methods for interacting with resources:

  • GET
    Make a GET request to retrieve data. GET requests will never cause an update or change to your data because they're safe and idempotent.
  • POST
    Use a POST request to create new resources. For example, make a POST request to a collection endpoint (like /domains) where the body of your request JSON is a new list.
  • PATCH
    Make a PATCH request to update a resource. With PATCH requests, you only need to provide the data you want to change.
  • PUT
    Use a PUT request to create or update a specific resource.
  • DELETE
    Make a DELETE request to remove a resource.

More about the REST implementation of our API is described in the introduction to rest section.

Checkdomain API is supporting the JSON schema standard. We decided to use that lightweight format because it is human-/machine-readable and easy to understand.

So instead of XML, HTTP POST parameters, or other serialization formats, most POST and PATCH requests require a valid JSON object in the request body. The API reference includes complete examples, but here's a quick look at the JSON format we're looking for in POST and PATCH requests:

Example of a request body
{
    "identifier": "CD1101-001",
    "type": "Owner",
    "gender": "F",
    "first_name": "Jane",
    "last_name": "Doe",
    "street": "Example Road 1",
    "city": "Exampleton",
    "postal_code": "1111",
    "country": "DE",
    "email": "jane.doe@exampleton.com",
    "phone": "+49 451 112233"
}
Example of a response body
{
    "id": 1,
    "identifier": "CD1101-001",
    "company": null,
    "gender": "M",
    "first_name": "John",
    "last_name": "Doe",
    "street": "Grosse Burgstrasse 27/29",
    "postal_code": "23552",
    "city": "Luebeck",
    "additional": null,
    "country": {
        "iso": "DE",
        "name": "Deutschland"
    },
    "email": "john.doe@example.com",
    "phone": "+49 451 709970",
    "fax": null,
    "_links": {
        "self": {
            "href": "/v1/contacts/1"
        }
    }
}