Введение в API

  • URL запроса
  • Авторизация
  • Формат взаимодействия - запрос
  • Формат взаимодействия - ответ
  • Ограничения
  • Объекты данных
  • URL запроса для обращения к серверу API

    Все запросы к API должны направляться на https://api.topvisor.ru с помощью метода POST.
    URL запроса должен включать в себя следующие данные:

    <!-- https://api.topvisor.ru/{версия}/{формат}/{оператор действия}/{имя сервиса}[/{имя метода}] -->

    Пример URL запроса:

    <!-- https://api.topvisor.ru/{версия}/{формат}/{оператор действия}/{имя сервиса}[/{метод}] --> https://api.topvisor.ru/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 // JSON
    Content-type: ЛЮБОЙ_ДРУГОЙ // form-data (не рекомендуется, например 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 и их объектов описан в разделе Сервисы.

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

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