Files
mtusi2026lab6/openspec/specs/api-conventions/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

15 KiB
Raw Blame History

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 в них — в нижнем регистре