Target.Mail.Ru API v2Александр Покатилов

API v1неконсистентностьнедостаточная документациялегаси-кодпроблемы с производительностью

REST

РесурсПолучение, обновление и удаление ресурса:

GET /api/v2/campaigns/123.json HTTP/1.1POST /api/v2/campaigns/123.json HTTP/1.1DELETE /api/v2/campaigns/123.json HTTP/1.1

Коллекция ресурсовПолучение списка ресурсов, создание ресурса:

GET /api/v2/campaigns.json HTTP/1.1POST /api/v2/campaigns.json HTTP/1.1

Указание полей ресурсаGET /api/v2/campaigns/123.json?fields=id,name HTTP/1.1

{ "id": 123, "name": "test"}

Связанные ресурсыПо умолчанию не отдаются.

Запрос связанного ресурса package:GET /api/v2/campaigns/123.json?fields=id,package HTTP/1.1

{ "id": 123, "package": { "id": 83, "name": "multiple_external_90_75_ppc", "description": "Внешние ссылки, клики" }}

Указание полей для связанных ресурсов:GET /api/v2/campaigns/123.json?fields=id,name,package__name HTTP/1.1

{ "id": 123, "name": "test", "package": { "name": "multiple_external_90_75_ppc" }}

Last-ModifiedЗапрос:

GET /api/v2/campaigns/123.json?fields=id,name HTTP/1.1

Ответ:HTTP/1.1 200 OKLast-Modified: Tue, 20 Nov 2014 04:58:08 GMT

{ "id": 123, "name": "test",}

If-Modified-SinceЗапрос:

GET /api/v2/campaigns/123.json?fields=id,name HTTP/1.1If-Modified-Since: Tue, 20 Nov 2014 04:58:08 GMT

Ответ:HTTP/1.1 304 Not Modified

ОшибкиЗапрос:

GET /api/v2/campaigns/123.json?fields=id,name HTTP/1.1Accept-Language: ru

Ответ:HTTP/1.1 404 Not Found

{ "code": "not_found", "message": "Запрашиваемый ресурс не найден"}

Получение коллекцииУказание полей ресурса + пагинация и фильтры:

GET /api/v2/campaigns.json?fields=id,name&offset=60&status=active HTTP/1.1

{ "items": [ { "id": 123, "name": "test" }, { "id": 456, "name": "test #2" } ], "count": 100, "offset": 60, "limit": 20}

Указание конкретных ресурсов:GET /api/v2/campaigns/123,456.json?fields=id,name HTTP/1.1

{ "items": [ { "id": 123, "name": "test" }, { "id": 456, "name": "test #2" } ], "count": 100, "offset": 60, "limit": 20}

Создание ресурсаЗапрос:

POST /api/v2/campaigns.json HTTP/1.1

{ "name": "Test campaign", "package": {"id": 18}, "targetings": { "regions": [188], "sex": "MF", "age": [20, 21], "pads": [{"id": 5206}] }}

Ответ:HTTP/1.1 201 CreatedLocation: http://target.mail.ru/api/v2/campaigns/123.jsonLast-Modified: Tue, 20 Nov 2014 04:58:08 GMT

{ "id": 123}

Создание ресурса #2С указанием полей:

POST /api/v2/campaigns.json?fields=id,name HTTP/1.1

{ "name": "Test campaign", "package": {"id": 18}, "targetings": { "regions": [188], "sex": "MF", "age": [20, 21], "pads": [{"id": 5206}] }}

Ответ:HTTP/1.1 200 OKLast-Modified: Tue, 20 Nov 2014 04:58:08 GMT

{ "id": 123, "name": "Test campaign"}

Создание ресурсовЗапрос:

POST /api/v2/campaigns.json HTTP/1.1

[ { "name": "Test campaign", "package": {"id": 18}, "targetings": { "regions": [188], "sex": "MF", "age": [20, 21], "pads": [{"id": 5206}] } }, ...]

Ответ:HTTP/1.1 201 CreatedLocation: https://target.mail.ru/api/v2/campaigns/123,456.json

[ {"id": 123}, {"id": 456}]

ОшибкиHTTP/1.1 400 Bad Request

{ "package": { "id": { "code": "unknown_resource", "message": "Несуществующий пакет" } }, "name": { "code": "required", "message": "Поле обязательно для заполнения" }}

HTTP/1.1 400 Bad Request

{ "banners": [ {}, { "title": { "code": "invalid_chars", "message": "Использованы запрещённые символы", "allowed": "abcdef" } } ]}

Обновление ресурсаЗапрос:

POST /api/v2/campaigns/123.json HTTP/1.1

{ "name": "Test campaign"}

Ответ:HTTP/1.1 204 No ContentLast-Modified: Tue, 20 Nov 2014 04:58:08 GMT

Обновление ресурса #2Запрос с указанием полей:

POST /api/v2/campaigns/123.json?fieds=id,name HTTP/1.1

{ "name": "Test campaign #2"}

Ответ:HTTP/1.1 200 OKLast-Modified: Tue, 20 Nov 2014 04:58:08 GMT

{ "id": 123, "name": "Test campaign #2"}

Обновление ресурсовЗапрос:

POST /api/v2/campaigns/123,456.json HTTP/1.1

[ { "id": 123, "status": "blocked", }, { "id": 456, "status": "blocked", }]

Ответ:HTTP/1.1 204 No Content

X-Target-SudoGET /api/v2/campaigns.json HTTP/1.1X-Target-Sudo: super.agency@mail.ru, d679a84537@agency_client

СжатиеСжатие показало, что чукча умер от сжатия:

GET /api/v2/campaigns.json HTTP/1.1Accept-Encoding: gzip, deflate

Продолжают работатьOAuth2ТроттлингПуш-нотификации

Начинает работатьАсинхронный API

Больше не работаетСтарая аутентификация с подписью запросов

Текущий статусЗакрытая альфа

Документация появится после бета-релиза.

Спасибо за вниманиеВопросы и предложения?