Устройство API

Аутентификация
Базовые типы данных
Базовые ошибки
Сжатие ответа
Лимиты на количество запросов в единицу времени
Тестирование

Стандарты 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,
    ...
}

Вам помогла эта статья?