Русский
EnglishВведение в API
URL запроса для обращения к серверу API
Все запросы к API должны направляться на https://api.topvisor.com с помощью метода POST.
URL запроса должен включать в себя следующие данные:
<!-- https://api.topvisor.com/{версия}/{формат}/{оператор действия}/{имя сервиса}[/{имя метода}] -->
- Версия API (v2);
- Формат возвращаемых данных (поддерживается только JSON);
- Оператор действия
- Имя сервиса
- Имя метода (необязательно)
- Заголовок: Content-type (необязательно, рекомендуется "application/json");
- Заголовок: User-Id;
- Заголовок: Authorization.
Пример URL запроса:
<!-- https://api.topvisor.com/{версия}/{формат}/{оператор действия}/{имя сервиса}[/{метод}] -->
https://api.topvisor.com/v2/json/get/users_2/profile/avatar
Доступ и авторизация
Для работы с API необходимо получить API Key.
Заголовки запроса для авторизации:
User-Id: %USER_ID% Authorization: bearer %USER_API_KEY%
Формат передачи данных
Все данные должны передаваться в кодировке utf-8.
Данные могут передаваться в теле запроса двумя способами: JSON или form-data.
Примеры заголовка запроса, устанавливающего тип передаваемых данных:
Content-type: application/json
Content-type: ЛЮБОЙ_ДРУГОЙ // например x-www-form-urlencoded (не рекомендуется)
Формат ответа
Ответ приходит в кодировке utf-8.
Поддерживается только один формат ответа: JSON.
{
"result": /* результат */, "nextOffset": /* число (может отсутствовать) */,
"total": /* число (может отсутствовать) */,
"errors":[/* массив ошибок (может отсутствовать) */],
"messages":[/* массив строк с информационными сообщениями (может отсутствовать) */]
}
Подробнее о nextOffset и total читайте на странице постраничная выборка.
Подробнее об errors читайте на странице обработка ошибок.
Ограничение на использование API
- В одном запросе на получение данных можно запросить не более 10 000 результатов
- С одного IP не более 5 одновременных запросов
- Для одного User-Id не более 5 одновременных запросов
При превышении ограничения API вернет ошибку с кодом 429.
Объекты данных
API позволяет получать, изменять и удалять объекты различных типов. Каждый сервис работает со своим типом данных. Перечень всех сервисов API и их объектов описан в разделе Сервисы.
Так к примеру сервис "Ключевые фразы" позволяет управлять такими объектами как "Ключевые фразы", "Группы" и "Папки".
Каждый тип данных имеет свой набор характеристик. Пример типа данных Ключевые фразы