Presentation of a new version of Target.mail.ru API.

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. Спасибо за внимание
Вопросы и предложения?