Files
mtusi2026lab4/openspec/specs/api-conventions/spec.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- carry the lab 3 solution over from mtusi2026lab3-safronov
  (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests,
  bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts,
  Dockerfile, compose, pyproject and uv lock
- merge Makefile, .gitignore and .dockerignore (the lab 3 versions only
  add lines to the skeleton, which is the same in lab 4) and
  .env.example (lab 4 skeleton names listed in the header)
- rename the compose project to mtusi-lab4 and the image to :lab4 so
  the stand does not reuse the lab 3 containers and volumes
- update AGENTS.md for lab 4: current lab, origin commit, contract and
  test files of the new skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:32:33 +03:00

230 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# api-conventions Specification
## Purpose
Общие правила HTTP API мессенджера: кодировка и формат JSON, единый
формат ошибок, заголовок `X-Request-Id`, представление времени и
идентификаторов. На них опираются все эндпоинты и клиенты, включая
публичный smoke.
## Requirements
### Requirement: JSON в UTF-8 без искажений
Ответы с телом SHALL иметь `Content-Type: application/json` в
кодировке UTF-8. Строки SHALL возвращаться клиенту в том виде, в каком
были приняты, включая кириллицу и emoji. Длины строк SHALL считаться в
Unicode code points.
#### Scenario: Unicode сохраняется
- **WHEN** клиент отправляет строковое поле `"Привет, мир 👋"`
- **THEN** в ответе и при последующем чтении это поле равно
`"Привет, мир 👋"` байт в байт после декодирования UTF-8
#### Scenario: Длина в code points
- **WHEN** клиент отправляет поле с ограничением 100 символов,
состоящее из 100 emoji
- **THEN** запрос принимается, хотя в UTF-8 это больше 100 байт
### Requirement: X-Request-Id на каждом ответе
Каждый ответ API SHALL содержать непустой заголовок `X-Request-Id`,
уникальный для запроса: успешный, с ошибкой, health, ответ на
неизвестный путь и ответ на непредвиденное исключение.
#### Scenario: Успешный ответ
- **WHEN** клиент выполняет любой успешный запрос
- **THEN** ответ содержит непустой `X-Request-Id`
#### Scenario: Ответ 500
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ 500 тоже содержит непустой `X-Request-Id`
#### Scenario: Разные запросы
- **WHEN** клиент выполняет два запроса подряд
- **THEN** значения `X-Request-Id` в ответах различаются
### Requirement: X-Instance-Id на каждом ответе
Каждый ответ, созданный API, SHALL содержать непустой заголовок
`X-Instance-Id` — идентификатор процесса, который обслужил запрос.
Это касается успешных ответов, ошибок, health, ответа на неизвестный
путь и неподдерживаемый метод, ответа на непредвиденное исключение.
Значение SHALL быть одним для всех ответов процесса, пока он работает,
и различаться у одновременно работающих процессов. Значение SHALL
состоять из ASCII-символов `A–Z`, `a–z`, `0–9`, `.`, `_`, `-`.
Требование не распространяется на ответы, которые создал не API, а
балансировщик при недоступности реплик.
#### Scenario: Instance id в успешном ответе и ошибке
- **WHEN** клиент получает ответы 200 и 201 и ответы с ошибками 400,
401, 404 и 409
- **THEN** каждый ответ содержит непустой `X-Instance-Id` допустимого
формата
#### Scenario: Instance id в health и служебных ответах
- **WHEN** клиент запрашивает `/health/live`, `/health/ready`,
`GET /api/v1/unknown` и `DELETE /api/v1/users`
- **THEN** каждый ответ содержит непустой `X-Instance-Id`
#### Scenario: Instance id в ответе 500
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ 500 тоже содержит `X-Instance-Id` того же процесса
#### Scenario: Одно значение на процесс
- **WHEN** клиент дважды подряд выполняет одну и ту же серию разных
запросов — к одному процессу API или через балансировщик к
нескольким репликам
- **THEN** против одного процесса все ответы содержат одно значение
`X-Instance-Id`; через балансировщик каждое значение встречается
больше чем в одном ответе, а во второй серии нет значений, которых не
было в первой
### Requirement: Единый формат ошибки
Любой ответ со статусом ≥ 400 SHALL иметь тело
`{"error": {"code": ..., "message": ..., "request_id": ...}}` без
других полей. `request_id` MUST совпадать с заголовком `X-Request-Id`.
`message` MUST быть непустым и MUST NOT раскрывать stack trace, пути к
файлам, имена внутренних классов, запросы к хранилищу или сам факт
существования недоступного объекта.
#### Scenario: Ошибка содержит request_id заголовка
- **WHEN** клиент получает любой ответ с ошибкой
- **THEN** тело соответствует формату, а `error.request_id` равен
значению заголовка `X-Request-Id`
#### Scenario: Нет тела FastAPI по умолчанию
- **WHEN** клиент получает ошибку валидации или 404
- **THEN** в теле нет ключа `detail`, есть только `error`
### Requirement: Соответствие статусов и кодов ошибок
Сервис SHALL использовать пары статус — `code`: 400 —
`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 —
`conflict`, 500 — `internal_error`, 503 — `unavailable`. Метод, не
поддерживаемый путём, SHALL давать 405 с `code` `invalid_request`.
#### Scenario: Неизвестный путь
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
#### Scenario: Неподдерживаемый метод
- **WHEN** клиент выполняет `DELETE /api/v1/users`
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
### Requirement: Невалидный запрос даёт 400
Сервис SHALL отвечать 400 `invalid_request`, а не 422, когда тело не
является корректным JSON; когда JSON не объект там, где ожидается
объект; когда в теле есть поля, не описанные в контракте; когда тип
значения не совпадает с контрактом. Значения MUST NOT приводиться к
нужному типу неявно. Обязательные строковые поля, состоящие только из
пробельных символов, SHALL считаться невалидными.
#### Scenario: Битый JSON
- **WHEN** клиент отправляет тело `{bad` с `Content-Type: application/json`
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Лишнее поле
- **WHEN** тело запроса содержит поле, которого нет в схеме контракта
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Неверный тип без приведения
- **WHEN** строковое поле передано числом `123`
- **THEN** ответ 400, значение не превращается в строку `"123"`
#### Scenario: Строка из пробелов
- **WHEN** обязательное строковое поле равно `" "`
- **THEN** ответ 400 с `code` `invalid_request`
### Requirement: Непредвиденная ошибка без деталей
Непредвиденное исключение SHALL давать ответ 500 с `code`
`internal_error` и общим сообщением. Детали ошибки MUST попадать только
в лог сервиса.
#### Scenario: Исключение внутри обработки
- **WHEN** при обработке запроса возникает непредвиденное исключение
- **THEN** клиент получает 500 `internal_error` без stack trace, а в
логе есть запись уровня `error` с traceback и тем же `request_id`
### Requirement: Представление времени и идентификаторов
Идентификаторы и время SHALL назначаться сервером. Идентификаторы SHALL
быть UUID в виде строки в нижнем регистре. Время SHALL передаваться в
формате RFC 3339 в UTC с суффиксом `Z` и точностью до микросекунд,
одинаковой при хранении и выдаче.
#### Scenario: Формат created_at
- **WHEN** клиент получает любой объект с `created_at`
- **THEN** значение оканчивается на `Z` и разбирается как RFC 3339 UTC
#### Scenario: Формат id
- **WHEN** клиент получает любой объект с `id`
- **THEN** значение — UUID в нижнем регистре
### Requirement: UUID на входе
Идентификатор, который передаёт клиент, — `chat_id` в пути и элементы
`member_ids` в теле — SHALL приниматься только как строка UUID в записи
8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`), как `format: uuid`
контракта. Шестнадцатеричные цифры SHALL приниматься в любом регистре:
UUID в верхнем регистре обозначает тот же идентификатор, что в нижнем.
В ответах идентификаторы остаются в нижнем регистре (требование
«Представление времени и идентификаторов»).
Значение другого типа (массив, объект, число, логическое значение, null)
и строка в другой записи (без дефисов, с префиксом `urn:uuid:`, в
фигурных скобках, с пробелами) SHALL давать 400 `invalid_request`, а не
500 и не успешный ответ. Такой запрос MUST NOT создавать объектов.
#### Scenario: UUID другого типа в теле
- **WHEN** Алиса создаёт чат, где `member_ids` содержит её id и ещё один
элемент — `[]`, `{}`, `123` или `false`
- **THEN** ответ 400 с `code` `invalid_request`, чат не появился в
списке чатов Алисы
#### Scenario: Не UUID в пути
- **WHEN** пользователь с действующей сессией запрашивает чат, историю
чата или отправляет сообщение с верным `Idempotency-Key`, а `chat_id`
в пути равен `123`, `false`, `[]` или `{}`
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Другая запись UUID
- **WHEN** участник передаёт id своего чата в пути или Алиса передаёт id
Боба в `member_ids`, записанный без дефисов, с префиксом `urn:uuid:`
или в фигурных скобках
- **THEN** ответ 400 с `code` `invalid_request`; ни чата, ни сообщения
не создано
#### Scenario: UUID в верхнем регистре в пути
- **WHEN** участник запрашивает свой чат, его историю и отправляет в
него сообщение, записав `chat_id` в верхнем регистре
- **THEN** ответы те же, что для `chat_id` в нижнем регистре, а
`id` и `chat_id` в них — в нижнем регистре