Files
mtusi2026lab3/openspec/specs/api-conventions/spec.md
T
ricoromaandClaude Opus 5.5 ab71c3b51e feat: put API replicas behind HAProxy
HAProxy 3.4 is the only published entry point; api runs as
API_REPLICAS replicas without ports, found through Docker DNS and
checked on /health/ready. Retries only on connection failure, LB errors
in the contract error format, resource limits and per-service secrets.
Adds scripts/stop-one.sh, LB-aware restart.sh, make replicas /
instances / lb_stats and replica tests driven by EXPECT_REPLICAS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 18:05:05 +03:00

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