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>
7.4 KiB
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 с
codenot_foundв формате ошибки
Scenario: Неподдерживаемый метод
- WHEN клиент выполняет
DELETE /api/v1/users - THEN ответ 405 с
codeinvalid_requestв формате ошибки
Requirement: Невалидный запрос даёт 400
Сервис SHALL отвечать 400 invalid_request, а не 422, когда тело не
является корректным JSON; когда JSON не объект там, где ожидается
объект; когда в теле есть поля, не описанные в контракте; когда тип
значения не совпадает с контрактом. Значения MUST NOT приводиться к
нужному типу неявно. Обязательные строковые поля, состоящие только из
пробельных символов, SHALL считаться невалидными.
Scenario: Битый JSON
- WHEN клиент отправляет тело
{badсContent-Type: application/json - THEN ответ 400 с
codeinvalid_request
Scenario: Лишнее поле
- WHEN тело запроса содержит поле, которого нет в схеме контракта
- THEN ответ 400 с
codeinvalid_request
Scenario: Неверный тип без приведения
- WHEN строковое поле передано числом
123 - THEN ответ 400, значение не превращается в строку
"123"
Scenario: Строка из пробелов
- WHEN обязательное строковое поле равно
" " - THEN ответ 400 с
codeinvalid_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 в нижнем регистре