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

by Redmadrobot

Slide 1

Slide 1 text

Проектирование API Андрей Муравьев [email protected] 20.09.2019

Slide 2

Slide 2 text

О чем поговорим?

Slide 3

Slide 3 text

3 REST refresher 1. Representational State Transfer   Архитектурный стиль, а не стандарт 2. Имеет ряд требований и свойств  Объектное взаимодействие, идентификация ресурсов (URI), отсутствие состояния, etc.  3. Может использоваться разный транспорт  HTTP — необязательное требование для REST  4. Могут использоваться разные форматы представления данных  JSON — необязательное требование для REST

Slide 4

Slide 4 text

4 Stateful Stateless Клиент: Кто такой Стив Джобс? Сервер: Основатель Apple Клиент: Когда он родился? Сервер: 24 февраля 1955 г. Клиент: Кто такой Стив Джобс? Сервер: Основатель Apple Клиент: Когда он родился? Сервер: Кто «он»?

Slide 5

Slide 5 text

5 И в этом нет ничего страшного Большинство API —  не "100%" REST

Slide 6

Slide 6 text

Проектирование

Slide 7

Slide 7 text

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: [{ ... }] }

Slide 8

Slide 8 text

8 CRUD-style POST https://example.com/api/send-notiﬁcation POST https://example.com/api/notiﬁcations Использование глагола: Добавление в коллекцию:

Slide 9

Slide 9 text

9 CRUD-style POST https://example.com/api/prepare-report POST https://example.com/api/report-requests Использование глагола: Добавление в коллекцию:

Slide 10

Slide 10 text

10 Структура URI GET/POST {...}/api/quizzes//questions GET {...}/api/users//quizzes//questions//answers GET {...}/api/answers?quiz=&user= POST {...}/api/answers?quiz= Вложенность: Фильтры:

Slide 11

Slide 11 text

11 Предпочтительно иметь один и только один способ сделать что-то GET https://example.com/api/objects GET https://example.com/api/admin/objects/ GET https://example.com/api/manager-objects/

Slide 12

Slide 12 text

12 Поведение метода не должно зависеть от типа клиента

Slide 13

Slide 13 text

13 Безопасность и идемпотентность Идемпотентные: GET, HEAD, OPTIONS, PUT, DELETE Не идемпотентные: POST, PATCH Безопасные: GET, HEAD, OPTIONS

Slide 14

Slide 14 text

14 Формат ошибок Не привязываемся к HTTP-коду { "error": { "code": "validation_error", "message": "Ошибка валидации данных", "incorrect_ﬁelds": [ { "name": "password", "description": "Пароль должен быть не менее 8 символов" } ] } } { "error": { "code": "cvs_processing_error", "message": "Некорректный csv-файл", } }

Slide 15

Slide 15 text

15 Формат ошибок 200 - только в случае успеха 500

Slide 16

Slide 16 text

16 Версионирование Стараться делать не ломающие изменения API GET https://example.com/api/v2/ GET https://example.com/api/objects?version=2   X-API-Version: v2

Slide 17

Slide 17 text

Оформление

Slide 18

Slide 18 text

There are only two hard things in Computer Science: cache invalidation and naming things. Phil Karlton

Slide 19

Slide 19 text

19 Именование GET https://example.com/api/messages POST https://example.com/api/messages GET https://example.com/api/messages/ GET https://example.com/api/message/

Slide 20

Slide 20 text

20 Именование GET https://example.com/api/complex-name-entities GET https://example.com/api/complex_name_entities

Slide 21

Slide 21 text

21 Типы и обязательность полей Указывайте их

Slide 22

Slide 22 text

22 Консистентность Оформляейте все консиcтентно ;)

Slide 23

Slide 23 text

23 История изменений

Slide 24

Slide 24 text

Безопасность

Slide 25

Slide 25 text

25 Не используйте GET для изменениях данных Это небезопасно и нарушает контракт HTTP

Slide 26

Slide 26 text

Где и как вести спецификацию API?

Slide 27

Slide 27 text

Confluence?

Slide 28

Slide 28 text

28   Тесты API   Документация   Реализация  на сервере Клиент   mock-сервер &'  Разработчики

Slide 29

Slide 29 text

Swagger?

Slide 30

Slide 30 text

OpenApi 3!

Slide 31

Slide 31 text

31   Тесты API   Документация   Реализация  на сервере Клиент   mock-сервер &'  Разработчики   OpenAPI-спецификация 31