«Как спроектировать и задокументировать хорошую спецификацию API»

Андрей Муравьёв, руководитель отдела серверной разработки

Transcript

1. Проектирование API Андрей Муравьев ma@redmadrobot.com 20.09.2019
2. О чем поговорим?
3. 3 REST refresher 1. Representational State Transfer 
 Архитектурный стиль, а не стандарт 2. Имеет ряд требований и свойств
 Объектное взаимодействие, идентификация ресурсов (URI), отсутствие состояния, etc.
 3. Может использоваться разный транспорт
 HTTP — необязательное требование для REST
 4. Могут использоваться разные форматы представления данных
 JSON — необязательное требование для REST
4. 4 Stateful Stateless Клиент: Кто такой Стив Джобс? Сервер: Основатель Apple Клиент: Когда он родился? Сервер: 24 февраля 1955 г. Клиент: Кто такой Стив Джобс? Сервер: Основатель Apple Клиент: Когда он родился? Сервер: Кто «он»?
5. 5 И в этом нет ничего страшного Большинство API —
 не "100%" REST
6. Проектирование
7. 7 Interface Segregation Лучше несколько маленьких интерфейсов, чем один большой GET https://example.com/api/news { news: [ { "title": "...", "content": "..." } ] } GET https://example.com/api/users/573 { news: { "title": "...", "content": "..." } } GET https://example.com/api/main { news: [ { "title": "...", "content": "..." } ], user: { "name": "...", "userpic_url": "..." }, banners: [{ ... }] }
8. 8 CRUD-style POST https://example.com/api/send-notification POST https://example.com/api/notifications Использование глагола: Добавление в коллекцию:
9. 9 CRUD-style POST https://example.com/api/prepare-report POST https://example.com/api/report-requests Использование глагола: Добавление в коллекцию:
10. 10 Структура URI GET/POST {...}/api/quizzes/<id>/questions GET {...}/api/users/<id>/quizzes/<id>/questions/<id>/answers GET {...}/api/answers?quiz=<id>&user=<id> POST {...}/api/answers?quiz=<id> Вложенность: Фильтры:
11. 11 Предпочтительно иметь один и только один способ сделать что-то GET https://example.com/api/objects GET https://example.com/api/admin/objects/ GET https://example.com/api/manager-objects/
12. 12 Поведение метода не должно зависеть от типа клиента
13. 13 Безопасность и идемпотентность Идемпотентные: GET, HEAD, OPTIONS, PUT, DELETE Не идемпотентные: POST, PATCH Безопасные: GET, HEAD, OPTIONS
14. 14 Формат ошибок Не привязываемся к HTTP-коду { "error": { "code": "validation_error", "message": "Ошибка валидации данных", "incorrect_fields": [ { "name": "password", "description": "Пароль должен быть не менее 8 символов" } ] } } { "error": { "code": "cvs_processing_error", "message": "Некорректный csv-файл", } }
15. 15 Формат ошибок 200 - только в случае успеха 500
16. 16 Версионирование Стараться делать не ломающие изменения API GET https://example.com/api/v2/ GET https://example.com/api/objects?version=2 
 X-API-Version: v2
17. Оформление
18. There are only two hard things in Computer Science: cache invalidation and naming things. Phil Karlton
19. 19 Именование GET https://example.com/api/messages POST https://example.com/api/messages GET https://example.com/api/messages/<id> GET https://example.com/api/message/<id>
20. 20 Именование GET https://example.com/api/complex-name-entities GET https://example.com/api/complex_name_entities
21. 21 Типы и обязательность полей Указывайте их
22. 22 Консистентность Оформляейте все консиcтентно ;)
23. 23 История изменений
24. Безопасность
25. 25 Не используйте GET для изменениях данных Это небезопасно и нарушает контракт HTTP
26. Где и как вести спецификацию API?
27.  Confluence?
28. 28 
 Тесты API 
 Документация 
 Реализация
 на сервере Клиент 
 mock-сервер &'
 Разработчики
29.  Swagger?
30.  OpenApi 3!
31. 31 
 Тесты API 
 Документация 
 Реализация
 на сервере Клиент 
 mock-сервер &'
 Разработчики 
 OpenAPI-спецификация 31
32. 32 Swagger UI
33. 33 ReDoc to the rescue!
34. 34 Инструменты https://openapi.tools/
35. Моки
36.  connexion 
 github.com/zalando/connexion
37. Спасибо!