Устройство API

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

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

GET /api/v1/campaigns.json

Создание кампании:

POST /api/v1/campaigns.json

Получение параметров конкретной кампании:

GET /api/v1/campaigns/1.json

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

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

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

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

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

API оперирует следующим набором базовых типов данных:

Тип данных

JSON-представление

Строка (String)

"value"

Целое число (Integer)

"123"

Десятичная дробь (Decimal)

"1.23"

Булево значение (Boolean)

"true" или "false"

Ничего (None)

null

Дата (Date)

"2013-08-18", формат YYYY-MM-DD, если явно не указан другой

Дата и время (Datetime)

"2013-08-28 16:49:34", формат YYYY-MM-DD HH:MM:SS если явно не указан другой, временная зона Europe/Moscow, если не указана другая

Список (List)

["value1", "value2"], элементы списка однородны

Объект (Object)

{"id": 1, "name": "Name"}, свойства объекта могут быть неоднородны

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

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

Ответы с ошибками имеют стандартные статусы 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. Идентификатор доступа и секретный ключ для работы с ним отличаются от тех, что используются для доступа к основному сервису. Как получить доступ к тестовой среде, описано в инструкции.