Стандартизация HTTP API · 4 курс

Стандартизация, сертификация и техническое документоведение · тема 1

Справочник

API

Стандартизация
HTTP API

Как из работающего кода получается API, который можно передать другой команде: договориться о контракте, описать его машиночитаемо, вернуть понятную ошибку, выпустить новую версию, не сломав клиентов, и заставить проверку работать без вас.

«API — это обещание одной программы другой. Стандартизация — способ записать обещание, проверка соответствия — способ убедиться, что оно выполняется.»

Дисциплина
Стандартизация, сертификация и техническое документоведение, 4 курс
Что понадобится
Python 3.12, редактор кода, браузер, аккаунт GitHub
Учебный стенд
Service Desk API — регистрация обращений в поддержку
Результат
Свой API с описанием, правилами и автоматической проверкой

§0Как устроен справочник

Материал разбит на восемь модулей. Каждый модуль отвечает на один вопрос работы с API и состоит из глав. Глава читается за один присест: объяснение, примеры на настоящем учебном сервисе, кадры экрана, частые ошибки, вопросы для самопроверки и шпаргалка.

Все примеры выполняются на одном проекте — Service Desk API. Это учебный сервис регистрации обращений в службу поддержки: сотрудник сообщает о проблеме, специалист меняет статус обращения. Проект открыт: github.com/MaximBytecamp/api-standard-template, его документация опубликована по адресу maximbytecamp.github.io/api-standard-template.

Каждое правило в справочнике сопровождается источником: пунктом стандарта, страницей документации или файлом из репозитория крупной компании. Цитата приводится в оригинале, под ней — перевод. Если правило принято только внутри одной компании, это сказано прямо.

Как читать примеры

Блоки с тёмным фоном — то, что вы набираете или отправляете. Блоки со светлым фоном и пунктирной рамкой — то, что возвращает сервер или печатает инструмент. Все выводы в справочнике получены запуском, а не написаны от руки.

§1Модули

Модуль 1

API как контракт

4 главы
  1. 1.1Контракт и проверка соответствияЧто обещает сервер клиенту, почему «работает» не значит «готово» и чем стандартизация отличается от проверки соответствия.готова
  2. 1.2Один обмен: запрос и ответПять частей запроса и три части ответа, заголовки, тело, коды состояния — на настоящих сообщениях учебного сервиса.готова
  3. 1.3Ресурсы и адресаЧто такое ресурс, чем коллекция отличается от элемента, зачем в адресе только существительные и где место идентификатору.готова
  4. 1.4Учебный стенд Service Desk APIЗапуск проекта, структура папок, пять операций, токены и первый запрос из браузера и из терминала.готова
Модуль 2

Правила HTTP

4 главы
  1. 2.1REST: ограничения стиляПять обязательных ограничений и одно необязательное, что каждое даёт на практике и почему «REST API» обычно выполняет их частично.готова
  2. 2.2Методы и их свойстваGET, POST, PUT, PATCH, DELETE; safe и idempotent показаны настоящими ответами на повторы запросов.готова
  3. 2.3Коды ответов2xx, 4xx, 5xx: какой код описывает какой исход, чем 401 отличается от 403, а 422 от 400, и как коды проверяются тестами.готова
  4. 2.4Параметры, тело, форматыЧетыре места параметра, пагинация и фильтры, media type, стиль JSON и три схемы вместо одной.готова
Модуль 3

OpenAPI

4 главы
  1. 3.1Зачем машиночитаемое описаниеРасхождение кода и README, что такое OpenAPI, его редакции 3.1 и 3.2.1, шесть видов читателей описания.готова
  2. 3.2Разделы документаinfo, servers, tags, paths, components, security — по одному разделу на настоящем описании учебного сервиса.готова
  3. 3.3FastAPI и OpenAPIПуть от строки в коде до поля в документе: метаданные, декоратор, схемы Pydantic, зависимости и доработка описания.готова
  4. 3.4Swagger UI и ReDocДва интерфейса одного документа, отправка запроса из браузера, кнопка Authorize и заголовки ответа.готова
Модуль 4

Ошибки и устойчивость

3 главы
  1. 4.1Problem Details (RFC 9457)Единый формат ошибки, поля type, title, status, detail, instance, свои расширения и страницы видов проблем.готова
  2. 4.2Диагностика ответаПорядок проверок, когда ответ не тот: разбор 401, 403, 404, 405, 422, 429 и 5xx на настоящих ответах сервиса.готова
  3. 4.3Заголовки контрактаETag с If-Match и If-None-Match, Idempotency-Key, заголовки лимитов и Retry-After, X-Request-Id и CORS.готова
Модуль 5

Версии и изменения

4 главы
  1. 5.1Четыре номера и SemVerВерсия формата, версия контракта, версия в пути и версия развёртывания; четыре решения GitHub, Graph, Azure и Box.готова
  2. 5.2Breaking changesЧто ломает клиента, почему GitHub и Azure отвечают по-разному, политика проекта и настоящий вывод oasdiff.готова
  3. 5.3Deprecation и SunsetПять этапов жизни операции, пометка в описании и два заголовка предупреждения в каждом ответе.готова
  4. 5.4CHANGELOG и ADRЖурнал изменений для потребителя API по Keep a Changelog и запись архитектурного решения из четырёх частей.готова
Модуль 6

Стандарт и его проверка

4 главы
  1. 6.1API Style GuideСвой стандарт проекта: уровни MUST, SHOULD и MAY по RFC 2119, структура документа и правило «каждое правило проверяемо».готова
  2. 6.2Линтер SpectralНабор spectral:oas, три собственных правила на JSONPath и настоящий вывод на намеренно испорченном контракте.готова
  3. 6.3Контрактные тесты31 тест проекта: проверки описания, проверки поведения и сверка выгруженного файла с кодом.готова
  4. 6.4CI и поиск breaking changesДве задачи сборки, сравнение версий контракта в pull request, защита ветки и настоящая красная сборка.готова
Модуль 7

Репозиторий API

4 главы
  1. 7.1Шаблон pull request и формы issueAPI First, форма предложения изменить контракт, чек-лист проверок и настоящие изменения в живом репозитории.готова
  2. 7.2Владельцы кода и безопасностьCODEOWNERS на файлы контракта, SECURITY.md с приватным каналом и Dependabot при закреплённых версиях.готова
  3. 7.3Опубликованная документацияСборка ReDoc, семь страниц видов ошибок для поля type и автоматическая выкладка на GitHub Pages.готова
  4. 7.4Стандарты компанийZalando, Microsoft, adidas, DigitalOcean и Box: где сходятся, где расходятся и как выбирать между вариантами.готова
Модуль 8

Практика

2 главы
  1. 8.1Свой API по правиламСемь шагов работы: предметная область, адреса, операции и коды, схемы и ошибки, реализация, проверки и документы репозитория.готова
  2. 8.2Отчёт и критерииЧто сохранять по ходу работы, как оформить доказательства и по каким двенадцати признакам работа принимается.готова

§2Материалы темы

Колода для показа122 слайда того же материала для проектора Учебный проектService Desk API: код, тесты, CI, шаблоны Документация APIReDoc и страницы видов ошибок Источники правилцитаты стандартов с переводом и файлы компаний План преподавателякак вести части, что уточнено в сценарии Список кадровчто снято и откуда

Стандартизация, сертификация и техническое документоведение · 4 курсМакаров Максим Николаевич

Кадр