Управление доменами с Selectel DNS API

В сегодняшней статье мы хотели бы поговорить об услуге, о которой ранее почти ничего не писали. Речь идёт о DNS-хостинге. Зарегистрировав домены в любой сторонней компании (мы услуг по регистрации доменов не оказываем), клиенты могут разместить их на наших NS-серверах совершенно бесплатно.
Наши NS-серверы расположены в Санкт-Петербурге, Москве, Екатеринбурге, Новосибирске, Нью-Йорке, Пало-Альто, Лондоне, Амстердаме и Франкфурте.

Актуальная ссылка на DNS API в Selectel.

Для повышения уровня надёжности и отказоустойчивости системы внедрена технология Anycast (подробнее об этом см. здесь).

Через нашу панель управления можно добавлять и удалять домены, а также добавлять и редактировать записи различных типов.

Сегодня мы представляем вам тестовую версию нашего DNS API для автоматизации работы с доменами и обновления информации о них на наших NS-серверах.

Возможности API

В настоящее время с помощью API можно осуществлять следующие операции:

• добавление, изменение и удаление доменов;
• добавление и редактирование ресурсных записей SRV, MX, CNAME, TXT, A, AAAA, NS, SPF (этот тип записей оставлен для совместимости, но к использованию не рекомендуется — см. RFC 7208) PTR (запись SOA создаётся автоматически при добавлении домена, значения MINIMUM и EXPIRE будет равны 86400 и 604800 соответственно);
• добавление и редактирование обратных записей для IP-адресов;
• пометка доменов тэгами.

Приступая к работе

Прежде чем начинать работу с API, нужно получить ключ здесь (для этого нужно перейти по указанной ссылке, далее всё просто и интуитивно понятно). Сам API расположен по адресу: https://api.selectel.ru/domains/v1/. Для авторизации ко всем запросам необходимо добавлять заголовок X-Token со значением ранее полученного ключа, например:

curl -H 'X-Token: ' https://api.selectel.ru/domains/v1/

API возвращает результат в формате JSON. В ответ на запросы на изменение, создание и обновление домена возвращается модель объекта, например:

{
	"user_id": 1,
	"name": "selectel.org",
 	"tags": [],
  	"change_date": null,
  	"create_date": 1427473275,
  	"id": 1
  }

В ответ на запрос об удалении домена будет возвращен ответ с кодом 204 (No Content). В случае ошибки при выполнении запроса будет возвращено её описание в следующем формате:

{
	“error”: “описание ошибки”,
	“code”: 400-599,
	“field”: “в каком поле была допущена ошибка”
}

Основные операции

В рамках этой статьи мы приводим лишь краткое описание операций, которые можно выполнять с помощью нашего API. Прочитать более подробное описание, а также выполнить типовые запросы можно на нашей тестовой площадке (страница сгенерирована с помощью популярного инструмента Swagger). Все адреса в описании запросов указаны относительно https://api.selectel.ru/domains/v1/.

Все данные в запросах передаются и возвращаются в формате JSON.

Операции с доменами

Добавление нового домена POST / Добавляет новый домен; в запросе необходимо передать имя нового домена и содержимое файла BIND-зоны (опционально).

Операция	Запрос	Описание
Получение списка доменов	GET /	Возвращает список доменов
Просмотр информации о домене	GET /{domain_id}	Возвращает сведения об указанном домене (имя, дата создания, дата изменения, тэги, идентификатор пользователя).
Обновление домена	PATCH /{domain_id}	Под обновлением домена понимается присвоение ему тэга. В запросе нужно передать идентификационный номер домена и идентификационные номера тэгов, которыми требуется отметить этот домен. Возвращает информацию об обновленном домене (имя, дата создания, дата изменения, тэги, идентификатор пользователя).
Удаление домена	DELETE /{domain_id}	Удаляет указанный домен; в случае успешного удаления будет возвращён ответ с кодом 204 (No Content).

Операции с ресурсными записями

Обновление записи PUT /{domain_id}/records/{record_id} изменяет параметры существующей ресурсной записи. В запросе нужно обязательно передать идентификационный номер номер записи, ее имя и тип. Для каждого типа записей в запрос включаются также индивидуальные параметры (подробнее см. на тестовой странице API).

Операция	Запрос	Описание
Получение списка ресурсных записей для указанного домена	GET /{domain_id}/records/	Возвращает сведения о ресурсных записях для указанного домена (идентификатор записи, имя, тип, время жизни, дату создания, дату изменения).
Обновление ресурсной записи	PUT /{domain_id}/records/{record_id}	Под обновлением записи понимается изменение её параметров. В запросе обязательно нужно передать идентификационный номер домена, имя записи, её идентификационный номер и тип. Для каждого типа записей в запрос включаются также индивидуальные параметры (подробнее см. на тестовой странице API).
Удаление ресурсной записи	DELETE /{domain_id}/records/{record_id}	Удаляет указанную ресурсную запись; в случае успешного удаления будет возвращён ответ с кодом 204 (No Content).

Операции с обратными записями

Добавление новой ресурсной записи PUT /ptr Возвращает информацию обо всех имеющихся обратных записях (идентификатор записи, обратный адрес, имя домена, идентификатор пользователя), включая новую.

Операция	Запрос	Описание
Получение списка обратных записей для указанного домена	GET /{domain_id}/ptr/	Возвращает сведения обратных записях для указанного домена (идентификатор записи, имя, тип, время жизни, дату создания, дату изменения).
Просмотр информации о обратной записи	GET /ptr/{ptr_id}	Возвращает информацию об указанной обратной записи (идентификатор записи, обратный адрес, имя домена, идентификатор пользователя).
Обновление обратной записи	PUT /ptr/{ptr_id}	Под обновлением обратной записи понимается изменение её параметров. В запросе нужно передать идентификационный номер записи, IP-адрес и имя домена.
Удаление ресурсной записи	DELETE /ptr/{ptr_id}	Удаляет указанную обратную запись; в случае успешного удаления будет возвращён ответ с кодом 204 (No Content).

Операции с тэгами

Многие из наших клиентов размещают у нас сотни и даже тысячи доменов. Чтобы упростить управление таким большим количеством доменов, в нашем API предусмотрена возможность добавления тэгов. С помощью тэгов можно структурировать список имеющихся доменов, разбив его на группы. Это позволяет ускорить поиск нужного домена, а также автоматизировать массовые операции с доменами. Основные операции с тэгами описаны в таблице ниже.

Операция	Запрос	Описание
Получение списка тэгов для указанного домена	GET /tags/	Возвращает список тэгов, содержащий имена и идентификаторы тэгов, а также список отмеченных тэгами доменов.
Получение списка доменов по тэгу	GET /tags/{tag_id}	Возвращает список доменов, отмеченных указанным тэгом
Добавление нового тэга	POST /tags/	Возвращает созданный тэг.
Обновление тэга	PUT /tags/{tag_id}	Под обновлением тэга понимается изменение его имени. В запросе нужно передать идентификационный номер тэга и его новое имя.
Удаление тэга	DELETE /tags/{tag_id}	Удаляет указанный тэг; в случае успешного удаления будет возвращён ответ с кодом 204 (No Content).

Скрипт для загрузки BIND-зоны

Недавно один из наших клиентов изъявил желание перенести к нам свои домены. Сложность ситуации заключалась в том, что нужно было перенести более
1000 А-записей. Понятно, что делать всё это вручную крайне сложно и неудобно. После долгих обсуждений мы написали скрипт для автоматизации переноса. Cкачать его можно здесь .

Чтобы загрузить BIND-зону, достаточно ввести команду вида:

$ bind_upload.py [-h] --key <key> --name <name> --zone <zone>

В качестве значения параметра −−key указываем ключ доступа к API, параметра −−name — имя домена, который будет добавлен. В параметре −−zone передаём путь к файлу зоны.

Скрипт возвращает информацию о добавленном домене в формате JSON. Если при добавлении какой-либо ресурсной записи возникают ошибки, информация о них будет включена в ответ.

Заключение

Как уже было сказано выше, наш DNS API сейчас функционирует в тестовом режиме. Сообщить обо всех замеченных ошибках, а также высказать пожелания и предложения по улучшению API, можно в комментариях к этому посту. Наиболее интересные идеи мы примем к сведению и постараемся реализовать.