APIСтандартизация
тема 1 Открыть слайдами →

Часть 1 из 15 · слайды 1–3

Что стандартизируем

Начинаем с того, что именно будем стандартизировать и чем стандартизация отличается от проверки.

  1. 1API как публичный контракт программы
  2. 2Что в этой теме означает «сертификация»
  3. 3Сегодня создаём новый учебный API

1API как публичный контракт программы

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

Стандартизировать необходимо:

  • адреса ресурсов
  • HTTP-методы
  • параметры
  • структуру JSON
  • HTTP status codes
  • формат ошибок
  • версионирование
  • документацию
  • безопасность
  • правила изменения API
  • проверку соответствия этим правилам
  1. CLIENTклиентская программа
  2. API CONTRACTURL · METHOD · PARAMETERS · BODY · RESPONSE · ERRORS · VERSION
  3. SERVERреализация на FastAPI

2Что в этой теме означает «сертификация»

Для обычного REST API нет единого международного органа, который выдаёт разработчику сертификат «правильного API». Поэтому в рамках дисциплины мы разделяем два процесса.

процесс 1

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

Создание набора правил, которым API должен соответствовать: как называть адреса, какие коды возвращать, как описывать ошибки.

процесс 2

Проверка соответствия

Доказательство того, что API эти правила действительно выполняет. Доказательство — результат проверки, а не мнение автора.

Позже в этой теме мы автоматизируем проверку:

OpenAPI→Linter→Contract tests→CI
СтандартЧем проверяется
API Style GuideSpectral
OpenAPI ContractOpenAPI validation
HTTP rulesTests
Security rulesSecurity review

3Сегодня создаём новый учебный API

До этого занятия учебного API не существует. Мы создаём отдельный учебный стенд, а production-сервисы не изменяем.

Предметная область — Service Desk API, система регистрации обращений в службу поддержки. Сотрудник сообщает о проблеме, специалист меняет статус обращения, пока проблема не решена.

ТехнологияРоль в проекте
Pythonязык реализации
FastAPIвеб-фреймворк: маршруты, обработка запросов
Pydanticсхемы данных и валидация тела запроса
OpenAPIмашиночитаемое описание контракта
Swagger UIинтерактивная документация по этому описанию
Учебный стенд
Service Desk API

tickets
├── создание
├── просмотр
├── изменение
└── удаление

Готовый эталон лежит в репозитории курса: api-standard-template/. Его структуру разберём в конце темы.

Кадр крупным планом