Files
mtusi2026lab4/openspec/changes/attachments/specs/api-conventions/spec.md
T
2026-10-20 23:44:50 +03:00

89 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Spec Delta
## MODIFIED Requirements
### Requirement: Соответствие статусов и кодов ошибок
Сервис SHALL использовать пары статус — `code`: 400 —
`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 —
`conflict`, 413 — `payload_too_large`, 415 — `unsupported_media_type`,
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` в формате ошибки
#### Scenario: Лимит и тип вложения
- **WHEN** участник загружает вложение больше 10 MiB, а затем текст с
`Content-Type: image/png`
- **THEN** ответы 413 с `code` `payload_too_large` и 415 с `code`
`unsupported_media_type` в формате ошибки
### 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` в них — в нижнем регистре