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