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. Якщо запит не виконувався, параметри потрібно буде вказувати самостійно.