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