Параметры,
тело, форматы

§1Четыре места параметра

Значение может приехать в запросе четырьмя путями, и выбор пути — часть контракта. В описании OpenAPI у параметра есть поле in, которое прямо называет место.

Смешение ролей ломает смысл запроса. Идентификатор в query (/tickets?id=…) превращает обращение к объекту в фильтрацию коллекции: вместо 404 клиент получит пустой список. Фильтр в пути (/tickets/open) выглядит как адрес объекта с идентификатором open — и ломается, как только у обращения появится такой идентификатор.

§2Пагинация: коллекция не бесконечна

Учебная база содержит три обращения, и их можно вернуть одним массивом. Но контракт пишется не под текущий объём данных: когда обращений станет двести тысяч, запрос GET /tickets без ограничения попробует вернуть их все.

Поэтому правило: коллекции, размер которых не ограничен, MUST поддерживать постраничный вывод. В учебном сервисе он устроен параметрами limit и offset.

GET /api/v1/tickets?limit=2&offset=0

HTTP/1.1 200
content-type: application/json

{
  "items": [ { … }, { … } ],
  "total": 3,
  "limit": 2,
  "offset": 0
}

Запрос с limit=500 не «подстроится» под максимум молча — он получит 422 и объяснение, какое значение допустимо. Если бы сервис молча заменил значение на максимальное, клиент счёл бы, что получил всю выборку, и часть данных была бы потеряна.

§3Фильтрация и сортировка

Фильтр — это query-параметр с понятным именем и объявленным набором значений. В учебном сервисе фильтр один:

GET /api/v1/tickets?status=open

Значение status ограничено перечислением open, in_progress, closed. Опечатка вернёт 422, а не пустой список: клиент узнает, что ошибся, а не решит, что обращений нет.

Общее требование: любой параметр, влияющий на выборку, должен быть описан в контракте. Параметр, не указанный в описании, известен только авторам сервиса, и остальные клиенты работают с неполным контрактом.

§4Media type: как читать тело

Тело запроса и ответа — набор байтов. Что это за байты, сообщает заголовок Content-Type с указанием media type.

Суффикс +json у application/problem+json говорит: формат основан на JSON, но имеет собственную структуру. Клиент, умеющий разбирать JSON, прочитает тело; клиент, знающий про Problem Details, поймёт смысл полей.

§5Стиль JSON

Имена полей — часть контракта, и менять их потом нельзя. Поэтому стиль выбирают один раз и применяют ко всем ресурсам сразу.

Ошибка не в выборе, а в смешении: created_at в одном ответе и updatedAt в соседнем заставляют клиента помнить исключения. Поэтому правило записывают в style guide и проверяют автоматически.

То же касается времени. В учебном сервисе дата и время передаются строкой в формате RFC 3339 в зоне UTC:

{
  "created_at": "2026-09-15T17:30:00Z",
  "updated_at": "2026-09-15T17:30:00Z"
}

Буква Z означает нулевое смещение. Такой формат сортируется как строка, однозначно разбирается любой библиотекой и не зависит от настроек сервера.

§6Три схемы вместо одной

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

class TicketCreate(BaseModel):
    model_config = ConfigDict(extra="forbid")
    title: str = Field(min_length=3, max_length=120)
    description: str = ""

Настройка extra="forbid" означает: поле, которого нет в схеме, — ошибка. Клиент, приславший свой id, получит 422 вместо тихого игнорирования. Это защищает от подмены серверных полей и от опечаток в именах.

§7Стиль проверяется линтером

Правило «свойства в snake_case» записано в .spectral.yaml проекта и применяется к описанию API целиком.

  json-properties-snake-case:
    description: Свойства JSON MUST быть записаны в snake_case.
    severity: error
    given: "$.components.schemas[*].properties"
    then:
      field: "@key"
      function: casing
      functionOptions:
        type: snake

Вот что печатает линтер, если в схему попало поле createdAt:

47:19    error  json-properties-snake-case  Свойства JSON MUST быть записаны
                                           в snake_case.
                                           components.schemas.Ticket.properties.createdAt

✖ 9 problems (7 errors, 2 warnings, 0 infos, 0 hints)

Сообщение называет файл, строку и точный путь до нарушения. Правило записано заранее, поэтому его применение не зависит от того, кто смотрит изменение.