Контракты ·
Как спроектировать API-контракт
Согласовать ресурсы, методы, схемы данных и поведение интеграции до разработки.
Кратко: за 2 минуты
Согласовать ресурсы, методы, схемы данных и поведение интеграции до разработки. Результат работы — OpenAPI Specification.
Когда применять
Урок относится к этапу «Контракты». Зафиксировать границы взаимодействия систем и однозначные критерии приемки. Задачу выполняют до реализации или согласования зависимого решения, чтобы команда опиралась на проверенные факты и однозначные договоренности.
Что это дает
Правильно выполненная работа снижает стоимость переделок, делает решение проверяемым и дает участникам единый источник информации. Практический результат фиксируется в артефакте «OpenAPI Specification».
Пошагово: как выполнить
- Опишите операции с точки зрения потребителя
- Зафиксируйте request и response schemas
- Добавьте примеры и ограничения полей
Критерии приемки
- Спецификация проходит lint
- Примеры соответствуют схемам
- Контракт согласован потребителями
Типичные ошибки
- Проектировать API по таблицам БД
- Оставлять optional поля без семантики
Инструменты
Пример
Плохой пример
«POST /orders принимает заказ и возвращает ID». Не описаны обязательные поля, права, форматы ответа и ошибки — клиенты будут реализовывать разные предположения.
Хороший пример
Учебный контракт POST /orders: аутентифицированный покупатель передает items с productId и целым quantity ≥ 1. При успехе — 201 и {"id":"ord-example","status":"created"}; при отсутствующем items — 400 и {"code":"VALIDATION_ERROR","field":"items"}; без аутентификации — 401. Правила повторной отправки согласованы отдельно через ключ идемпотентности. Схема и примеры проверяются OpenAPI-валидатором и контрактными тестами потребителя.
Шаблон
OpenAPI Specification
Скачать рабочий лист этого урока
Посмотреть и скачать шаблонРабочий артефакт
Рабочий артефакт
OpenAPI Specification
Учебный контракт POST /orders: аутентифицированный покупатель передает items с productId и целым quantity ≥ 1. При успехе — 201 и {"id":"ord-example","status":"created"}; при отсутствующем items — 400 и {"code":"VALIDATION_ERROR","field":"items"}; без аутентификации — 401. Правила повторной отправки согласованы отдельно через ключ идемпотентности. Схема и примеры проверяются OpenAPI-валидатором и контрактными тестами потребителя.
- Методы
- Ошибки
- Сценарии
- Версии
Контроль качества
Спецификация интеграции
Спецификация проходит lint
После релизов, изменения требований, обновления целей и появления новых рисков.
Контекст, проблему, доказательство, владельца, срок и критерий приемки.
Перед отметкой выполнено: Спецификация проходит lint
Как применять
Начинайте с влияния на пользователя, продукт и команду. Затем проверьте реализуемость, критерии качества и формат доказательства результата. Хороший пункт чеклиста объясняет, какую проблему закрываем, как выполняем работу и по каким признакам считаем ее завершенной.
Короткие ответы
Частые вопросы
Зачем выполнять пункт «Как спроектировать API-контракт»?
Правильно выполненная работа снижает стоимость переделок, делает решение проверяемым и дает участникам единый источник информации. Практический результат фиксируется в артефакте «OpenAPI Specification».
С чего начать выполнение?
Опишите операции с точки зрения потребителя
Как понять, что пункт выполнен?
Спецификация проходит lint
Какая ошибка чаще всего мешает результату?
Проектировать API по таблицам БД
Режим обучения
Тест по теме
Проверка понимания
Ответьте на вопросы по материалу и получите итоговый отчет: что понято хорошо, а что стоит перечитать.
Для углубленного изучения
Редакция Ariol · Версия 3 · Обновлено
Независимая экспертная проверка не заявлена.
Что обновлено
- — Обновлено: Название, Заголовок поиска, Описание поиска.
- — Обновлено: Пример, Плохой пример, Скачиваемый шаблон, Заголовок поиска, Поисковые фразы.
Материал предназначен для обучения. Адаптируйте рекомендации к внутренним регламентам компании и условиям проекта.
Предложить исправление через контакты Ariol