DNS API

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

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

Начало работы

Перед началом работы получите ключ. Сам API расположен по адресу https://api.selectel.ru/domains/v1/. В GET-запросах к этому адресу нужно добавлять полученный ключ. B POST-, PUT-, PATCH- и DELETE-запросах в заголовок нужно добавить параметр X-Sid: <ключ>, но здесь есть один нюанс: ключ представляет собой структуру вида _, но при добавлении параметра в заголовки часть с user_id должна быть отброшена (параметр будет выглядеть так: X-Sid:), при этом в query-параметры ключ нужно добавлять целиком: api_key=<ключ>.

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

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

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

{
 “error”: “error description”,
 “code”: 400-599,
 “field”: “field that the error occurred in”
}

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

Ниже приведено краткое описание операций, которые можно выполнять с помощью нашего API. Все адреса в описании запросов указаны относительно https://api.selectel.ru/domains/v1/. Все данные в запросах передаются и возвращаются в формате JSON.

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

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

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

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

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

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

Тэги

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

Основные операции с тэгами описаны в таблице ниже:

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

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

Скрипт для автоматизации переноса можно скачать здесь.
Чтобы загрузить BIND-зону введите команду вида:

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

В качестве значения параметра –key укажите ключ доступа к API, параметра –name - имя домена, который будет добавлен. В параметре –zone передается путь к файлу зоны. Скрипт возвращает информацию о добавленном домене в формате JSON. Если при добавлении какой-либо ресурсной записи возникают ошибки, информация о них будет включена в ответ.