1.11. Работа с API

Для работы с API требуется токен. Токен привязан к учётной записи и позволяет управлять всеми услугами, которые в ней доступны, в том числе делегированными.

1. Откройте раздел «API».
2. На вкладке «Данные доступа» отметьте «Я соглашаюсь с пользовательским соглашением и правилами предоставления услуг» и нажмите «Активировать токен»:

Токен действует 6 месяцев:

• Если использовался — с момента последнего использования.
• Если не использовался — с момента создания.

Лимит запросов — 60 в минуту.

Лимит представляет собой счётчик, который каждую секунду увеличивается на 1 с максимальным значением 60. Например, если если за секунду исчерпать весь лимит, то уже через секунду можно будет сделать 1 запрос. Если после исчерпания лимита не делать запросов, то через минуту лимит вернётся к стандартному значению 60. Лимиты в секунду/час/сутки и т. д. не применяются.

Ответ на каждый вопрос содержит HTTP-заголовки:

• X-RateLimit-Limit: 60 — лимит запросов.
• X-RateLimit-Remaining: XX — количество запросов, которое осталось до исчерпания лимита.

При достижении лимита:

• Возвращается код ответа 429.
• Ответ содержит сообщение об ошибке: «Too Many Requests per minute. Look on Retry-After and X-RateLimit-* headers».
• В ответ добавляется заголовок Retry-After с количеством секунд, которое нужно подождать перед отправкой нового запроса.
• На почту и в подключённые мессенджеры отправляется уведомление (но не чаще одного раза в неделю).

Ограничения доступа настраиваются в разделе «API» на вкладке «Ограничение доступа»:

Логика работы следующая:

• Список адресов пуст — доступ открыт для всех.
• В списке есть один или несколько адресов — доступ открыт только для адресов из списка, для остальных закрыт.

Адреса и подсети в формате CIDR добавляются в список разрешённых кнопкой «Добавить IP в список разрешённых». Все добавленные адреса отображаются в списке ниже. К каждому из них можно добавить примечание или удалить из списка.

Ознакомиться со списком методов, их описаниями, протестировать их работу и получить примеры кода можно в разделе «API» на вкладке «Документация». Вкладка состоит из нескольких блоков.

В блоке «Методы» отображается список доступных методов:

Блок с названием выбранного метода содержит его подробное описание:

• Метод отправки запроса — GET или POST.
• URL — адрес, по которому должен отправляться запрос.
• Параметры — список доступных параметров, типы данных для каждого из них и варианты доступных значений.
• Подробное описание метода и возвращаемых им значений (не для всех методов).

В левой части блока «Выполнение запроса» расположена форма для быстрой отправки запроса от имени текущей учётной записи, в правой выводится код ответа и результат отправленного запроса:

При выполнении какого-либо действия в панели управления система автоматически фиксирует данные последнего запроса к соответствующему методу и хранит их 10 минут. В течение этого времени в документации на странице метода будет видна дата и время его последнего вызова, можно будет просмотреть список переданных ему параметров и подставлять эти параметры в форму запроса. Для каждого метода хранятся данные только 1 последнего запроса, выполненного в текущей учётной записи.

В блоке «Пример кода» выводится пример кода для использования текущего метода с помощью cURL или библиотеки HostingAPI:

• Текущий активный токен автоматически подставляется в строку с параметром $auth_token. Если токен не активен, его нужно будет активировать и подставлять в код вручную.
• Параметры из формы после выполнения запроса автоматически подставляются в строку с параметром $post. Если запрос не выполнялся, параметры нужно будет указывать самостоятельно.