DevConf 2016 "Великолепный API без Rest", Констатин Якушев (Badoo) О чём пойдёт речь: 1. Мы используем Google Protobuf для документации и как протокол для нативных платформ. На вебе они оборачиваются в JSON через http + server-sent events. Расскажу, как это помогает в документации и в процессах. 2. Все поля и сообщения документируются, для новых функций пишется подробный обзор со скриншотами "по шагам" и примерами сообщений и ответов. Покажу, как это выглядит и зачем нужно. 3. Версионирование осуществляется через флаги "Клиент умеет такую-то возможность" или "Клиент знает о таком-то изменении протокола". Это гораздо лучше, чем номер версии и резко увеличивает гибкость системы. Разберу с конкретными примерами, как это работает. 4. Кроме того, расскажу об отдельной команде в Badoo, занимающейся развитием этой истории.

1. Константин Якушев
Великолепный API без REST

2. Константин Якушев
Великолепный API без REST

3. Telegram group:
bit.ly/devconf-common

4. Мои API
2014 — Everada
2015 — Timepad
2016 — Badoo
http://shop.oreilly.com/product/9780596801694.do

5. API
435
активных
A/B-тестов
5-10
изменений
каждую
неделю
314млн.
пользователей

6. У нас тут
своя атмосфера

8. Используйте json через http,
уведомления через websocket

9. Обычно
Клиент php-код
websocket/SSE
запрос
ответ
уведомление

10. Одно соединение
Клиент proxy php-код
постоянное соединение
запрос
запрос
ответ
ответ
уведомление
уведомление

11. Google protobuf
✦ Бинарный
✦ Есть файл описания и автогенерация
✦ Нет сложившихся паттернов

12. message Person {
optional string name = 1; // SRV-123 Full name
required int32 id = 2; // SRV-123 id for URL
repeated string photo_url = 3;
}

13. Бинарный протокол
тоже отлично подойдёт
Используйте json через http,
уведомления через websocket

14. Передавайте данные,
а не их представление

15. GET /popularity_history
GET /current_user
GET /rank

16. GET_POPULARITY_PAGE

17. GET_SUPER_POWERS_PAGE

20. Передавайте данные,
а не их представление
Промо-страницы передавайте
«как есть»

21. Автоматически собирайте
документацию из полей

22. message SuperPowerPage {
repeated Promo promos = 1; // List of promos
optional string button_text = 2; // Text to display
// in button
}
message Promo {
optional string photo_url = 1; // Person’s photo
optional string icon_url = 2; // Icon image
optional string promo_text = 3; // Text under promo
}

25. Автоматически собирайте
документацию из полей
Пишите документацию руками по
реальным экранам

26. Если придётся ломать
совместимость, добавляйте
номера версий /v1, /v2

28. Обычно
Version 2:
✦ Обрезка работы/образования на сервере
✦ Новый формат поля User
✦ 3 новых уведомления
✦ …

30. Поэтапное включение
1. Клиент ставит флаг «Я знаю про новый механизм»
2. Сервер показывает новое поведение такому клиенту
3. Когда все клиенты поддерживают флаг, его можно убрать

31. Сколько версий у
приложений badoo?
iOS 6
Только Россия и Великобритания
Только Android в Бразилии
50% пользователей
5% платящих пользователей
Только Windows Phone
Android 2.3

32. Клиент Сервер
Я поддерживаю
такую-то фичу
Проверяю, нужно ли её включать
Включай
Включаю

33. Если придётся ломать
совместимость, добавляйте
номера версий /v1, /v2
Версионируйте флагами
поддержки функций

34. Бинарные протоколы
не хуже http
Передавать
«чистые данные»
совсем не
обязательно
Документацию
лучше писать про
конкретные случаи
Итого
Версионировать
лучше флагами
поддержки, а не
номерами версий

35. Думайте же головой

36. Что читать
https://techblog.badoo.com/blog/2016/05/11/crazy-agile-api/

37. Что смотреть
https://www.youtube.com/watch?v=Wkw4TOBEKUY

38. Спасибо!