start

Различия

Показаны различия между двумя версиями страницы.


Предыдущая версия
start [07/11/2023 09:40] (текущий) karlov
Строка 1: Строка 1:
 +====== Хостинг Украина API ======
  
 +<callout type="warning" title="Внимание!">
 +Документация находится в процессе доработки. Описания методов могут изменяться/дополняться.
 +</callout>
 +
 +Для API используется специальная прослойка между вызовами через веб-интерфейс панели управления. Она позволяет авторизоваться по токену, выполнять запросы от имени пользователя и получать ответы в формате [[https://ru.wikipedia.org/wiki/JSON|JSON]].
 +
 +<grid>
 +<col sm="6">
 +
 +<callout type="success" title="Преимущества подхода:">
 +  * Большинство действий, которые можно выполнять через панель управления, могут быть выполнены через API.
 +  * Всегда актуальное API. Основной функционал панели управления сразу доступен через API.
 +  * Стабильность работы API. Работа панели управления ежедневно проверяется тысячами пользователей.
 +</callout>
 +
 +</col>
 +<col sm="6">
 +
 +<callout type="warning" title="Нюансы подхода:">
 +  * Некоторые функции API могут быть изменены без предупреждения. Однако по нашим наблюдениям появление новых параметров должно оказывать минимальное влияние на работу существующих функций API.
 +</callout>
 +
 +</col>
 +</grid>
 +
 +===== Методы =====
 +
 +  * Учётная запись:
 +    * [[service]]
 +  * [[hosting]]
 +    * [[extra]]
 +  * Домены:
 +    * [[domain|Регистрация и др.]]
 +    * [[dns|Настройка и др.]]
 +  * [[vps]]
 +  * [[dedicated]]
 +  * [[storage]]
 +  * [[mysql]]
 +  * [[mongo]]
 +  * [[redis]]
 +  * [[billing]]
 +  * API:
 +    * [[get_id]]
 +    * [[params|Список параметров]]
 +
 +===== Использование =====
 +
 +Работа с API выполняется с помощью отправки запросов к нужным [[#Методы|методам]]. Необходимые для выполнения метода данные передаются с помощью GET или POST. В случае успеха метод выполняет нужное действие или возвращает какие-либо данные. 
 +
 +Адрес для отправки запросов API:<code>https://adm.tools/actions/метод</code>
 +
 +==== Авторизация ====
 +
 +Для авторизации используется [[https://tools.ietf.org/html/rfc6750|Bearer token]]. Система выполняет только те запросы, в которых присутствует заголовок ''Authorization: Bearer токен'', где ''токен'' — это ваш [[https://adm.tools/user/api/|токен API]].
 +
 +==== Отправка запросов ====
 +
 +<callout type="info" title="Примечания:">
 +  * Тестировать запросы к API можно в панели управления в [[https://adm.tools/user/api/#/tab-sandbox|API-песочнице]]. 
 +  * Простой класс для работы с API доступен на [[https://github.com/ukraine-com-ua/API|GitHub]].
 +  * В Python при использовании библиотеки requests необходимо добавлять заголовок ''User-Agent'', например:<code php>
 +headers = {
 +    'Authorization': 'Bearer токен',
 +    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
 +}</code>
 +</callout>
 +
 +Пример простого скрипта:<code php>
 +<?php
 +
 +$ch = curl_init("https://adm.tools/action/path/to/method/?gdata1=value3&gdata2=value4");
 +curl_setopt_array($ch, array(
 +    CURLOPT_POST => true,
 +    CURLOPT_RETURNTRANSFER => true,
 +    CURLOPT_HTTPHEADER => array("Authorization: Bearer токен"),
 +    CURLOPT_POSTFIELDS => http_build_query(["data1" => "value1", "data2" => "value2", "data3" => ["1" => "subvalue1", "2" => "subvalue2"]]),
 +    CURLOPT_VERBOSE => true,
 +));
 +
 +$response = curl_exec($ch);
 +</code>Где:
 +  * ''gdata*'' — GET-параметры с нужными данными (если используются в методе).
 +  * ''data*'' — POST-параметры с нужными данными (если используются в методе).
 +
 +==== Коды ответов ====
 +
 +  * ''200 OK'' — метод отработал успешно без ошибок или исключений.
 +  * ''400 Bad Request'' — в процессе работы метода возникла ошибка или исключение.
 +  * ''401 Unauthorized'' — некорректный токен.
 +  * ''403 Forbidden'' — ошибка доступа к методу.
 +  * ''405 Method Not Allowed'' — попытка обращения к несуществующему методу.
 +  * ''429 Too Many Requests'' — слишком много запросов (см. [[#Лимиты|лимиты]]).
 +
 +==== Общая структура ответов ====
 +
 +<code json>
 +{
 +    "result": false, // Результат выполнения
 +    "response": [],  // Полезная нагрузка, если есть
 +    "messages": {    // Список сообщений
 +        "success": [
 +            "..."
 +        ],
 +        "error": [
 +            "..."
 +        ]
 +    }
 +}
 +</code>
 +
 +==== Лимиты ====
 +
 +Количество запросов к API:
 +  * В час — не более 300.
 +  * В день — не более 5000.
 +
 +В ответе на каждый запрос к любому методу возвращаются HTTP-заголовки с информацией о лимитах:
 +  * ''X-RateLimit-Hour'' — возможное количество запросов в час.
 +  * ''X-RateLimit-Hour-Remaining'' — оставшееся количество запросов в час.
 +  * ''X-RateLimit-Day'' — возможное количество запросов в сутки.
 +  * ''X-RateLimit-Day-Remaining'' — оставшееся количество запросов в сутки.
 +
 +Повторные одинаковые запросы не проверяются и не фильтруются. При использовании API нужно самостоятельно контролировать, чтобы используемый скрипт не отправлял случайные повторные запросы, когда это не нужно.
 +
 +===== Недоступно через API =====
 +
 +Некоторые операции можно выполнять только вручную через панель управления или Telegram-бота, например операции по работе с резервными копиями.