SmartQuery /ВОПРОС → ПРИМЕР → ПОНЯТНЫЙ ОТВЕТ
Веб-разработка

Контракт API на примере каталога фильмов

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

Операции и ответы

Пример договорённостей для ресурса movies
ОперацияУспешный ответЧто определить отдельно
GET /movies200, список и данные пагинацииpage≥1, limit1…100, стабильная сортировка
GET /movies/{id}200, объект404 для отсутствующего фильма
POST /movies201, созданный объектОбязательные поля, авторизация, Location
PUT /movies/{id}200 либо204Полное представление ресурса
PATCH /movies/{id}200 либо204Правила частичного обновления
DELETE /movies/{id}204, без телаПоведение при повторном удалении

Это выбранный контракт, а не единственный допустимый набор ответов. PUT и PATCH не следует описывать как одну операцию с произвольно необязательными полями: смысл частичного обновления нужно задать явно.

Описать параметр в OpenAPI

openapi: 3.1.1
info:
  title: Movie API example
  version: 1.0.0
paths:
  /movies:
    get:
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Список фильмов
        '400':
          description: Недопустимые параметры

Что ещё включить

  • Схемы объектов: типы, обязательность, формат даты и допустимость null.
  • Понятный формат ошибки: код, описание и идентификатор запроса без внутренних stack traces.
  • Права на чтение и изменение, ограничения частоты запросов.
  • Примеры валидных и невалидных запросов, включая пустой список и крайние значения пагинации.

После согласования сверьте реализацию и тесты с контрактом. Документ, который расходится с реальными ответами сервера, перестаёт выполнять свою основную задачу.

Документация