Files
mtusi2026lab2/openspec/specs/api-conventions/spec.md
T
ricoromaandClaude Opus 5.5 7b775a29a9 chore: carry over lab 1 solution into lab 2 skeleton
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>
2026-09-30 22:11:46 +03:00

7.4 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: Единый формат ошибки

Любой ответ со статусом ≥ 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 в нижнем регистре