Устройство API


API реализован в виде набора «ресурсов» (объектов предметной области) и «методов» (операций над ресурсами), что в некоторой степени соответствует REST-идеологии. Основным отличием является то, что многие методы позволяют оперировать ресурсами со сложной структурой, включающей в себя другие ресурсы с произвольным уровнем вложенности или списки других ресурсов. Многие методы также поддерживают операции над несколькими ресурсами одного типа.

Каждый ресурс имеет один или несколько типов URL-адресов. Различные операции над ресурсом реализованы в виде различных методов протокола HTTP. Например, получение списка рекламных кампаний:


GET /api/v2/campaigns.json
Создание кампании:

POST /api/v2/campaigns.json
Получение параметров конкретной кампании:

GET /api/v2/campaigns/1.json
Для подавляющего большинства методов входные и выходные данные представлены в формате JSON. Соответственно, HTTP-запросы и ответы имеют тип application/json. Для запросов GET или DELETE, не имеющих тела, тип указывать необязательно.

Для валидации входных и генерации выходных данных для каждого ресурса описана одна или несколько «структур данных». В описании каждого метода указано, какими структурами он оперирует.

Аутентификация

Для аутентификации и авторизации в API используется протокол OAuth2. Его реализация описана в отдельной статье. Регистрация клиентов для работы с API через OAuth2 пока осуществляется в ручном режиме по заявке в Службу поддержки (ads_api@vk.team). Как получить доступ к API, описано в инструкции.

Базовые типы данных

API оперирует следующим набором базовых типов данных:
Сложные типы данных, основанные на базовых, описаны в документации по методам и ресурсам.

Базовые ошибки

Ответы с ошибками имеют стандартные статусы HTTP-ответов. В теле ответа при этом указана более подробная информация об ошибке в формате JSON (тип ответа-ошибки — application/json).

  • 400 — ошибка валидации структуры данных, присланной в запросе;
  • 401 — отсутствие подписи для осуществления аутентификации или же неправильное её значение (заголовок Authorization должен содержать корректное значение access_token);
  • 403 — операция запрещена для аккаунта, чьим секретным ключом (access_token) был подписан запрос;
  • 404 — запрашиваемый ресурс не найден;
  • 405 — ресурс не поддерживает данный HTTP-метод;
  • 413 — тело запроса слишком велико;
  • 429 — превышение лимита на количество запросов в единицу времени;
  • 500 — непредвиденная ошибка.

Сжатие ответа

Если ваш клиент поддерживает сжатие, в запросе можно передавать заголовок:

Accept-Encoding: gzip, deflate

Лимиты на количество запросов в единицу времени

Сервис ограничивает количество запросов в единицу времени. Ограничения действуют для промежутков времени, равных секунде, часу и дню. Ограничения привязаны к календарным периодам времени.

Пользовательские лимиты подсчитываются для каждого пользователя независимо. К примеру, если в системе существует ограничение в 10 запросов в минуту к определенному методу, то это значит, что каждый пользователь может сделать не более 10 запросов в минуту.

Лимиты могут быть настроены по-разному для различных пользователей или групп пользователей. Поэтому всегда стоит опираться только на данные, полученнные в реальном времени.

Текущие ограничения возвращаются в HTTP-заголовках ответа на любой запрос (для различных методов будут различные значения):

X-RateLimit-RPS-Limit: value     # количество запросов в секунду 
X-RateLimit-Hourly-Limit: value  # количество запросов в час 
X-RateLimit-Daily-Limit: value   # количество запросов в день
Количество действий до достижения порога также возвращается в HTTP-заголовках ответа:

X-RateLimit-RPS-Remaining: value    # сколько запросов можно произвести до окончания текущей секунды 
X-RateLimit-Hourly-Remaining: value # сколько запросов можно произвести до окончания текущего часа 
X-RateLimit-Daily-Remaining: value  # сколько запросов можно произвести до окончания текущего дня
Информацию о лимитах для конкретного пользователя также можно получить с помощью запроса

GET /api/v2/throttling.json

Ответ содержит текущее значение лимитов, а также количество оставшихся запросов по ресурсам, для которых лимиты заданы.

{
    "REMARKETINGUSERSLIST": {
        "v2": {
            "READ": {
                "remaining": {
                    "60": 1
                },
                "limits": {
                    "60": 1
                }
            },
            "CREATE": {
                "remaining": {
                    "60": 0
                },
                "limits": {
                    "60": 0
                }
            }
        },
        "v3": {
            "READ": {
                "remaining": {
                    "3600": 200
                },
                "limits": {
                    "3600": 200
                }
            },
            "CREATE": {
                "remaining": {
                    "3600": 10
                },
                "limits": {
                    "3600": 10
                }
            }
        },
        "all": {
            "READ": {
                "remaining": {
                    "3600": 200
                },
                "limits": {
                    "3600": 200
                }
            },
            "CREATE": {
                "remaining": {
                    "60": 1
                },
                "limits": {
                    "60": 1
                }
            }
        }
    }
Для ресурса могут быть заданы как общие лимиты, так и лимиты на использование метода определенной версии. Версия соответствует неймспейсу. Так, в приведенном примере c помощью метода /api/v2/remarketing/users_lists/<id>.json можно сделать не более одного GET-запроса в минуту, а создать новый список нельзя, с помощью /api/v2/remarketing/users_lists/<id>.json можно прочитать информацию по 200 спискам в час, а создать 10 списков в час. И при этом с помощью запросов любых версий суммарно нельзя прочитать информацию по более чем 200 спискам в час, а создавать можно не более 1 списка в час.

После релиза новой версии метода, мы будем постепенно уменьшать лимиты использования для предыдущих версии того же самого ресурса.

Тестирование

Для тестирования работы с API существует отдельный тестовый экземпляр сервиса: https://target-sandbox.my.com. Идентификатор доступа и секретный ключ для работы с ним отличаются от тех, что используются для доступа к основному сервису. Как получить доступ к тестовой среде, описано в инструкции.

Стандарты API

Следующие правила актуальны для всех методов.

Параметры запроса

Название
Формат
Default
Описание
Пример
fields
<field_name>[,<field_name>]*
Зависит от ресурса
Список полей для объекта верхнего уровня.
fields=id,name
limit
integer
20
Количество объектов в выдаче. Максимум 50.
limit=10
offset
integer
0
Сдвиг по объектам в выдаче.
sorting
[-]?<field_name>[,[-]?<field_name>]*
-
Сортировка по полям объекта. Список сортируемых полей уникален для каждого ресурса. <field_name> - ASC -<field_name> - DESC
sorting=id,-created
_<field_name>__<field_lookup>
<value>[,<value>]*
-
Фильтры по полям объекта.

Список фильтруемых полей уникален для каждого ресурса.

Нельзя фильтровать по полям вложенных объектов.
_id__in=1,2,3 _status__ne=active _updated__gt=2018-01-01 00:00:00
_<field_name>
<value>
-
Фильтр на равенство по полю объекта. Правила такие же как в _<field_name>__<field_lookup>
_id=1
offset=500

Field lookups (стандартные названия)

  • ne - не равно
  • lt - меньше чем
  • lte - менее или равно
  • gt - более чем
  • gte - более или равно

Ответ

Коллекция

{
    "count": int,  // общее число объектов, после применения всех остальных параметров
    "offset": int, // текущее смещение
    "limit": int, // количество объектов в выдаче
    "items": [{
        "<field_name>": field_value,
        ...
    }, ...]
}
Объект

{
    "<field_name>": field_value,
    ...
}
Вам помогла эта статья?