61 lines
4.2 KiB
Markdown
61 lines
4.2 KiB
Markdown
# HTTP API и ошибки
|
||
|
||
## Источник контракта
|
||
|
||
Backend генерирует OpenAPI из собственного публичного API. Frontend использует
|
||
производное описание контракта и типизированный клиент. Изменения проходят
|
||
[contract workflow](../development/runtime-openapi-verification.md).
|
||
API имеет prefix `/api/v1`; Swagger публикуется для локальной разработки по
|
||
environment policy, а не используется frontend в runtime.
|
||
|
||
## Validation и identity
|
||
|
||
Backend преобразует и проверяет входные данные на общей HTTP-границе.
|
||
Неизвестные свойства запроса удаляются; сам факт их передачи не обещает отказа.
|
||
Проверка формата не заменяет бизнес-ограничения и проверку доступа к счёту.
|
||
Аутентификация подтверждает личность пользователя; accountId из URL сам по себе
|
||
не доказывает доступ к брокерским данным.
|
||
|
||
## Error contract
|
||
|
||
Общая граница обработки HTTP-ошибок возвращает `application/problem+json`
|
||
со `status` и публичным `code`.
|
||
Неожиданный exception возвращает `500` / `INTERNAL_SERVER_ERROR`, без исходного
|
||
message/stack. Типичный ответ:
|
||
|
||
```json
|
||
{ "status": 401, "code": "UNAUTHORIZED" }
|
||
```
|
||
|
||
Для input validation контракт требует `400`, `VALIDATION_ERROR` и `errors` как
|
||
массив `{ pointer, detail }`, где pointer адресует поле запроса. Это требование
|
||
не считается проверенным одним описанием OpenAPI: нужна проверка реального
|
||
HTTP-ответа после всех стадий обработки запроса.
|
||
|
||
**Требует ручной проверки:** согласованность деталей ошибок валидации полей
|
||
в полном HTTP-потоке пока не подтверждена. Известно расхождение формата ошибок
|
||
между стадиями валидации и формирования ответа; наличие описания в OpenAPI
|
||
не доказывает передачу ожидаемых `pointer` и `detail`.
|
||
|
||
Ответ не включает автоматически все поля RFC (`type`, `title`, `instance`).
|
||
Добавление обязательного поля является изменением публичного контракта.
|
||
Клиент выбирает поведение по публичному коду, а не по внутреннему тексту ошибки.
|
||
|
||
## Domain errors и auth
|
||
|
||
Специальный code определяется сценарием; общее преобразование ошибок и безопасная
|
||
форма ответа принадлежат HTTP-границе. Auth endpoints используют свои status и cookie
|
||
operations: [Authentication](../features/authentication.md).
|
||
T-Bank token failure и временная недоступность имеют разные значения:
|
||
[Connection API](../features/tbank-connection.md#api). Raw upstream/Prisma errors
|
||
и secrets не передаются frontend.
|
||
|
||
## Граница доказательства
|
||
|
||
Сравнение OpenAPI подтверждает согласованность схем, а не результат каждого
|
||
запроса. Безопасная обработка неожиданной ошибки проверяется отдельно.
|
||
Валидация, доступ, статусы и cookie требуют проверки полного HTTP-потока;
|
||
атомарность хранения — проверки с изолированной реальной базой.
|
||
Известное ограничение сквозных проверок описано в
|
||
[проверке backend](../development/backend-workflow.md#локальная-проверка).
|