Введение в API

URL запроса

Авторизация

Формат взаимодействия - запрос

Формат взаимодействия - ответ

Ограничения

Объекты данных

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/user/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 и их объектов описан в разделе Сервисы.

Так к примеру сервис "Ключевые фразы" позволяет управлять такими объектами как "Ключевые фразы", "Группы" и "Папки".

Каждый тип данных имеет свой набор характеристик. Пример типа данных Ключевые фразы