Managing Domains with the Selectel DNS API
Today, we wanted to discuss a service we haven’t really written about before — DNS hosting. After registering a domain with any third-party company (as we do not register domains), clients can host them on our nameservers absolutely for free.
We have servers in St. Petersburg, Moscow, Yekaterinburg, Novosibirsk, New York, Palo Alto, London, Amsterdam, and Frankfurt.
For added reliability and fault-tolerance, our system implements anycast technology.
In our control panel, you can add and delete domains, as well as add and edit different kinds of DNS records.
Today, our DNS API is available for automating work with domains and updating their information on our name servers.
API Functions
The following operations can be performed with the API:
- add, change, and delete domains;
- add and edit resource records: SRV, MX, CNAME, TXT, A, AAAA, NS, SPF (which is here for compatibility, but not recommended for use–see RFC 7208), and PTR; when a domain is added, SOA records are created automatically with MINIMUM and EXPIRE values set to 86400 and 607800 respectively;
- add and edit reverse records for IP addresses;
- tag domains.
Getting Started
You’ll first need to get a key here (just follow the link, the rest is fairly self-explanatory). The actual API is located at https://api.selectel.ru/domains/v1/. Requests will only be authorized if they include the X-Token header with the key you get from the link above. For example:
curl -H 'X-Token: ' https://api.selectel.ru/domains/v1/
API responses are given in JSON format. Requests to change, create, and update a domain return object models. For example:
{
"user_id": 1,
"name": "selectel.org",
"tags": [],
"change_date": null,
"create_date": 1427473275,
"id": 1
}
Requests to delete a domain return a 204 (No Content) code. If an error occurs while carrying out a request, a description will be returned in the following format:
{
“error”: “error description”,
“code”: 400-599,
“field”: “field that the error occurred in”
}
Basic Operations
In this article, we’ll only briefly describe the operations that can be performed from our API. For a more detailed description of these operations and to perform typical requests, visit our test platform at https://support.selectel.ru/domains/doc (pages are generated using Swagger). All descriptions are given in relation to https://api.selectel.ru/domains/v1/.
All request data is sent and returned in JSON format.
Domain Operations
| Operation | Request | Description |
|---|---|---|
| Add new domain | POST / | Adds a new domain; the request must include the name of the new domain and the contents of the BIND zone file (optional) |
| List domains | GET / | Returns a list of domains |
| Get domain information | GET /{domain_id} | Returns information on the given domain (name, data created, date last modified, tags, user ID) |
| Update domain | PATCH /{domain_id} | ‘Update domain’ means updating its tags. The domain identification number and identification number of the tags required to mark the domain must be included in the request. Returns information on the updated domain (name, date created, date last modified, tags, user ID). |
| Delete domain | DELETE /{domain_id} | Deletes the given domain; if successful, returns code 204 (No Content). |
Resource Record Operations
| Operation | Request | Description |
|---|---|---|
| Add new resource record | PUT /{domain_id}_records | Adds a new resource record. The record’s identification number, name, and type must be included in the request. Each record type also requires its own specific parameters (visit the API documentation for more detailed information). |
| List resource records for specific domain | GET /{domain_id}/records | Returns information on resource records for the given domain (record identifier, name, type, lifespan, date created, date last modified). |
| Update resource record | PUT /{domain_id}/records/{record_id} | ‘Update record’ means changing its parameters. The domain’s identification number and record’s name, identification number, and type need to be included in the request. Each record type also requires its own specific parameters (visit the API documentation for more detailed information). |
| Delete resource record | DELETE /{domain_id}/records/{record_id} | Deletes the given resource record; if successful, returns code 204 (No Content). |
| Delete domain | DELETE /{domain_id} | Deletes the given domain; if successful, returns code 204 (No Content). |
Reverse Record (PTR) Operations
| Operation | Request | Description |
|---|---|---|
| Add new resource record | PUT /ptr/ | Returns information on all modified reverse records (record identifier, return address, domain name, user ID), including new ones. |
| List resource records for specific domain | GET /{domain_id}/ptr/ | Returns information on reverse records for the given domain (record identifier, name, type, lifespan, date created, date last modified). |
| View reverse record information | GET /ptr/{ptr_id} | Returns information on the given reverse record (record identification, return address, domain name,user ID) |
| Update reverse record | PUT /ptr/{ptr_id} | ‘Update reverse record’ means changing its parameters. The domain’s identification number, IP address, and domain must be included in the request. |
| Delete reverse record | DELETE /ptr/{ptr_id} | Deletes the given reverse record; if successful, returns code 204 (No Content). |
Tag Operations
A lot of clients host hundreds or even thousands of domains with us. To make managing so many domains easier, we gave our API the ability to use tags. With tags, you can structure a list of existing domains by breaking it into groups. This lets you search for the domains you need faster and automate array operations for domains. Basic tag operations are described in the table below.
| Operation | Request | Description |
|---|---|---|
| List tags for specific domain | GET /tags/ | Returns a list of name and identifier tags as well as a list of tagged domains. |
| List domains by tag | GET /tags/{tag_id} | Returns a list of domains marked by the given tag. |
| Add new tag | POST /tags/ | Returns the created tag. |
| Update tag | PUT /tags/{tag_id} | ‘Update tag’ means changing its name. The tag’s identification number and new name must be included in the request. |
| Delete tag | DELETE /tags/{tag_id} | Deletes the given tag; if successful, returns code 204 (No Content). |
Script for Uploading BIND Zones
Recently, one of our clients expressed an interest in migrating their domains to our DNS. The problem was that more than 1,000 A records needed to be transferred. Obviously, doing this all manually would be extremely complicated and terribly inconvenient. After discussing this at great length, we wrote a script to automate the migration process. You can dowload it here.
To upload a BIND zone, just enter the command:
$ bind_upload.py [-h] --key --name --zone
For the –key parameter value, enter your API access key; for –name, enter the domain name to be added. For the –zone parameter, enter the path to the zone file.
The script returns information on the added domain in JSON format. If any errors occur while adding a resource record, information on the error will be included in the response.
Conclusion
As we’ve already said, our DNS API is already available. Please let us know about any errors or suggestions for improving the API in the comments below. We’ll keep these in mind when making further adjustments and updates to the API.