Copy the committed lab 1 sources as-is: src/, student-tests/, bench/, Dockerfile, docker-compose.yml, pyproject.toml, uv.lock, .python-version, config_example.toml, AGENTS.md, CLAUDE.md, .claude/, openspec/, .graphifyignore and KNOWN_ISSUES.md. Lab 1 evidence stays in the lab 1 repository. Merge the new skeleton files with own sections: Makefile (lab 2 targets plus own run, docker, bench and common targets), .gitignore, .dockerignore and .env.example. Rename the image to mtusi-messenger:lab2 and point AGENTS.md at lab 2. The application is still the in-memory lab 1 implementation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
146 lines
7.4 KiB
Markdown
146 lines
7.4 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: Единый формат ошибки
|
||
|
||
Любой ответ со статусом ≥ 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 в нижнем регистре
|