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