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.
We introduced a sandbox to have you on the safe side. With the sandbox you are able to test your API implementation against a real answering API with an up-to-date structure. But as simple as it is, the sandbox only verifies some basic things like: correct URI, authentication and is data set. It does not validate the data you are sending in.
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.
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.
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.
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.
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:
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:
{
"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"
}{
"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"
}
}
}