Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
265 lines
15 KiB
Markdown
265 lines
15 KiB
Markdown
# 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`, 413 — `payload_too_large`, 415 — `unsupported_media_type`,
|
||
429 — `rate_limited`, 500 — `internal_error`, 503 — `unavailable`.
|
||
Метод, не поддерживаемый путём, SHALL давать 405 с `code`
|
||
`invalid_request`. Ответ 429 SHALL содержать заголовок `Retry-After` —
|
||
положительное целое число секунд.
|
||
|
||
#### Scenario: Неизвестный путь
|
||
|
||
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
|
||
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
|
||
|
||
#### Scenario: Неподдерживаемый метод
|
||
|
||
- **WHEN** клиент выполняет `DELETE /api/v1/users`
|
||
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
|
||
|
||
#### Scenario: Лимит и тип вложения
|
||
|
||
- **WHEN** участник загружает вложение больше 10 MiB, а затем текст с
|
||
`Content-Type: image/png`
|
||
- **THEN** ответы 413 с `code` `payload_too_large` и 415 с `code`
|
||
`unsupported_media_type` в формате ошибки
|
||
|
||
#### Scenario: Лимит одновременных загрузок
|
||
|
||
- **WHEN** все места загрузки процесса заняты и очередь ожидания полна
|
||
(`attachments`, «Одновременные загрузки реплики»), и участник
|
||
загружает вложение
|
||
- **THEN** ответ 429 с `code` `rate_limited` в формате ошибки, с
|
||
непустыми `X-Request-Id` и `X-Instance-Id` и с `Retry-After` —
|
||
положительным целым числом
|
||
|
||
### 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 на входе
|
||
|
||
Идентификатор, который передаёт клиент, SHALL приниматься только как
|
||
строка UUID в записи 8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`),
|
||
как `format: uuid` контракта. Это `chat_id` и с лабы 4
|
||
`attachment_id` в пути, элементы `member_ids` и с лабы 4 элементы
|
||
`attachment_ids` в теле. Шестнадцатеричные цифры 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` в них — в нижнем регистре
|
||
|
||
#### Scenario: Идентификаторы вложений в другой записи
|
||
|
||
- **WHEN** участник запрашивает метаданные и байты вложения, записав
|
||
`attachment_id` без дефисов, с префиксом `urn:uuid:` или в фигурных
|
||
скобках, и отправляет сообщение с таким элементом в `attachment_ids`
|
||
- **THEN** каждый ответ 400 с `code` `invalid_request`, сообщение не
|
||
создано
|
||
|
||
#### Scenario: Идентификаторы вложений в верхнем регистре
|
||
|
||
- **WHEN** участник запрашивает метаданные и байты вложения и
|
||
отправляет сообщение с ним, записав id вложения в верхнем регистре
|
||
- **THEN** ответы те же, что для id в нижнем регистре, а `id` и
|
||
`attachment_ids` в них — в нижнем регистре
|