- 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>
13 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: 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 с
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 в нижнем регистре
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 с
codeinvalid_request, чат не появился в списке чатов Алисы
Scenario: Не UUID в пути
- WHEN пользователь с действующей сессией запрашивает чат, историю
чата или отправляет сообщение с верным
Idempotency-Key, аchat_idв пути равен123,false,[]или{} - THEN ответ 400 с
codeinvalid_request
Scenario: Другая запись UUID
- WHEN участник передаёт id своего чата в пути или Алиса передаёт id
Боба в
member_ids, записанный без дефисов, с префиксомurn:uuid:или в фигурных скобках - THEN ответ 400 с
codeinvalid_request; ни чата, ни сообщения не создано
Scenario: UUID в верхнем регистре в пути
- WHEN участник запрашивает свой чат, его историю и отправляет в
него сообщение, записав
chat_idв верхнем регистре - THEN ответы те же, что для
chat_idв нижнем регистре, аidиchat_idв них — в нижнем регистре