1.11. Работа с API

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

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

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

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

Лимиты на количество запросов к API:

• В час — не более 3600 запросов.
• В сутки — не более 28800 запросов.

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

• С текущими лимитами:
  • X-RateLimit-Hour: 3600 — в час.
  • X-RateLimit-Day: 28800 — в сутки.
• С количеством запросов, которое осталось до исчерпания лимитов:
  • X-RateLimit-Hour-Remaining: XXX — в час.
  • X-RateLimit-Day-Remaining: XXXX — в сутки.

Количество запросов в секунду/минуту не ограничивается.

При превышении лимита в ответ на запрос будет возвращаться сообщение об ошибке со значением лимита и оставшимся количеством секунд до его сброса:

• «Too Many Requests per hour. Limit 3600. Pause XXX seconds» — для часового лимита.
• «Too Many Requests per day. Limit 28800. Pause XXXX seconds» — для суточного лимита.

Также при достижении лимитов отправляется соответствующее уведомление на почту и в подключённые мессенджеры (но не чаще одного раза в неделю).

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

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

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

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

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

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

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

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

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

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

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

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