Стандартизация, сертификация и техническое документоведение · 4 курс · тема 1
API как публичный контракт программы
На этом занятии нас интересует не только серверный код. Мы рассматриваем API как контракт между двумя программами: что клиент вправе ожидать от сервера и как проверить, что сервер это выполняет.
Часть 1 →Что внутри
Тот же материал, что и в колоде из 122 слайдов, но текстом и по частям: читать можно подряд, а можно открыть нужную часть.
-
1Что стандартизируем
Начинаем с того, что именно будем стандартизировать и чем стандартизация отличается от проверки.
слайды 1–3 · 3 разворотов -
2Запрос, ответ, ресурс
Правила пишутся для обмена сообщениями между программами, поэтому сначала разберём один такой обмен.
слайды 4–8 · 5 разворотов -
3Архитектурный стиль REST
Ресурс, метод и код ответа пришли в HTTP API из архитектурного стиля REST. Разберём его ограничения.
слайды 9–15 · 7 разворотов -
4Правила HTTP API
REST задаёт принципы, но не говорит, как назвать адрес и какой код вернуть. Это решают правила HTTP API.
слайды 16–33 · 18 разворотов -
5Практика: контракт
Правил уже достаточно, чтобы спроектировать контракт Service Desk и найти ошибки в чужом.
слайды 34–36 · 3 разворотов -
6OpenAPI
Контракт спроектирован. Теперь его нужно записать так, чтобы документ не разошёлся с кодом.
слайды 37–53 · 17 разворотов -
7FastAPI и документация
Документ OpenAPI можно писать руками, а можно получать из кода. Учебный проект делает второе.
слайды 54–60 · 7 разворотов -
8Единый формат ошибок
Успешные ответы описаны схемами. Ошибкам нужен такой же единый формат на весь API.
слайды 61–65 · 5 разворотов -
9Версии и изменения
Контракт вместе с ошибками готов. Следующий вопрос — как его менять, не ломая клиентов.
слайды 66–75 · 10 разворотов -
10Стандарт и его проверка
Правила именования, ошибок и версий уже есть. Их нужно собрать в один стандарт и проверять автоматически.
слайды 76–86 · 11 разворотов -
11Стандарты реальных команд
Так устроен стандарт учебного проекта. Посмотрим, как это делают OpenAPI Initiative, Zalando, Microsoft и другие.
слайды 87–94 · 8 разворотов -
12Репозиторий API на GitHub
Компании публикуют не только описание API, но и правила работы с его репозиторием.
слайды 95–103 · 9 разворотов -
13Заголовки и совместимость
Репозиторий оформлен. Остались правила, которые клиент видит в каждом ответе: заголовки версии, лимитов и совместимости.
слайды 104–113 · 10 разворотов -
14Практическая работа
Все механизмы собраны в учебном эталоне. Его структура становится образцом для вашей работы.
слайды 114–120 · 7 разворотов -
15Итог темы
Практическая работа закрывает тему. Соберём весь процесс в одну схему.
слайды 121–122 · 2 разворотов