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

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

3.
REST

4.
Ресурс
Получение, обновление и удаление ресурса:
GET /api/v2/campaigns/123.json HTTP/1.1
POST /api/v2/campaigns/123.json HTTP/1.1
DELETE /api/v2/campaigns/123.json HTTP/1.1

5.
Коллекция ресурсов
Получение списка ресурсов, создание ресурса:
GET /api/v2/campaigns.json HTTP/1.1
POST /api/v2/campaigns.json HTTP/1.1

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

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

8.
Запрос связанного ресурса 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": "Внешние ссылки, клики"
}
}

9.
Указание полей для связанных ресурсов:
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"
}
}

10.
Last-Modified
Запрос:
GET /api/v2/campaigns/123.json?fields=id,name HTTP/1.1
Ответ:
HTTP/1.1 200 OK
Last-Modified: Tue, 20 Nov 2014 04:58:08 GMT
{
"id": 123,
"name": "test",
}

11.
If-Modified-Since
Запрос:
GET /api/v2/campaigns/123.json?fields=id,name HTTP/1.1
If-Modified-Since: Tue, 20 Nov 2014 04:58:08 GMT
Ответ:
HTTP/1.1 304 Not Modified

12.
Ошибки
Запрос:
GET /api/v2/campaigns/123.json?fields=id,name HTTP/1.1
Accept-Language: ru
Ответ:
HTTP/1.1 404 Not Found
{
"code": "not_found",
"message": "Запрашиваемый ресурс не найден"
}

13.
Получение коллекции
Указание полей ресурса + пагинация и фильтры:
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
}

14.
Указание конкретных ресурсов:
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
}

15.
Создание ресурса
Запрос:
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}]
}
}

16.
Ответ:
HTTP/1.1 201 Created
Location: http://target.mail.ru/api/v2/campaigns/123.json
Last-Modified: Tue, 20 Nov 2014 04:58:08 GMT
{
"id": 123
}

17.
Создание ресурса #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}]
}
}

18.
Ответ:
HTTP/1.1 200 OK
Last-Modified: Tue, 20 Nov 2014 04:58:08 GMT
{
"id": 123,
"name": "Test campaign"
}

19.
Создание ресурсов
Запрос:
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}]
}
},
...
]

20.
Ответ:
HTTP/1.1 201 Created
Location: https://target.mail.ru/api/v2/campaigns/123,456.json
[
{"id": 123},
{"id": 456}
]

21.
Ошибки
HTTP/1.1 400 Bad Request
{
"package": {
"id": {
"code": "unknown_resource",
"message": "Несуществующий пакет"
}
},
"name": {
"code": "required",
"message": "Поле обязательно для заполнения"
}
}

22.
HTTP/1.1 400 Bad Request
{
"banners": [
{},
{
"title": {
"code": "invalid_chars",
"message": "Использованы запрещённые символы",
"allowed": "abcdef"
}
}
]
}

23.
Обновление ресурса
Запрос:
POST /api/v2/campaigns/123.json HTTP/1.1
{
"name": "Test campaign"
}
Ответ:
HTTP/1.1 204 No Content
Last-Modified: Tue, 20 Nov 2014 04:58:08 GMT

24.
Обновление ресурса #2
Запрос с указанием полей:
POST /api/v2/campaigns/123.json?fieds=id,name HTTP/1.1
{
"name": "Test campaign #2"
}
Ответ:
HTTP/1.1 200 OK
Last-Modified: Tue, 20 Nov 2014 04:58:08 GMT
{
"id": 123,
"name": "Test campaign #2"
}

25.
Обновление ресурсов
Запрос:
POST /api/v2/campaigns/123,456.json HTTP/1.1
[
{
"id": 123,
"status": "blocked",
},
{
"id": 456,
"status": "blocked",
}
]
Ответ:
HTTP/1.1 204 No Content

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

27.
Сжатие
Сжатие показало, что чукча умер от сжатия:
GET /api/v2/campaigns.json HTTP/1.1
Accept-Encoding: gzip, deflate

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

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

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

31.
Текущий статус
Закрытая альфа
Документация появится после бета-релиза.

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