API conventions и поведенческий контракт

Паспорт документа

• Статус документа: living standard
• Актуально на: 29 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении API-контракта, auth-flow, error-модели или handoff-процесса
• Область применения: общие правила HTTP API поверх живого OpenAPI-контракта Qadam
• Связанные документы:
  • Карта API-маршрутов
  • Change Log для frontend-команды
  • Памятка для frontend-команды

Цель документа

OpenAPI остаётся машиночитаемым источником истины по endpoint и схемам. Этот документ фиксирует общие соглашения API-поведения: auth, error model, backward compatibility и ожидания для клиентов.

1. Источники истины

По приоритету:

1. runtime OpenAPI: https://qadam.2fab.app/api/openapi.json
2. versioned artifact: qadam-core/apps/api/openapi/openapi.json
3. обзорная карта: api-routes.md
4. frontend handoff и frontend changelog

Если человекочитаемый документ расходится с OpenAPI, contract source of truth — OpenAPI.

2. Base prefix и versioning

• Канонический base prefix: /api/v1
• Swagger UI публикуется на /api/docs
• OpenAPI JSON публикуется на /api/openapi.json

Новые клиентские интеграции не должны проектироваться на неверсированные пути.

3. Auth conventions

Web

• Каноническая модель — httpOnly cookies
• access cookie: qadam_at
• refresh cookie: qadam_rt
• основной browser-flow: login -> auth/me -> refresh -> logout

Non-web clients

• Допускается Bearer token в Authorization header
• Это дополнительный transport mode, а не замена web cookie model

4. Success responses

У API нет одного глобального envelope вида { data }. Реальный response shape определяется OpenAPI и конкретным контроллером.

Практическое правило:

• не предполагать единый envelope по всему API;
• читать response types только из OpenAPI/generated contract;
• если endpoint возвращает объект-обёртку вроде { profile }, { addresses }, { user, seller }, это часть контракта, а не “временный слой”.

5. Error model

Доменные ошибки сериализуются в общий формат:

{
  "statusCode": 409,
  "errorCode": "EMAIL_TAKEN",
  "message": "..."
}

Базовые правила:

• errorCode — канонический идентификатор для UI и интеграций;
• message — человекочитаемое описание;
• точная карта кодов ошибок живёт в shared constants и domain filter;
• для field-level UI нельзя ориентироваться только на текст message.

6. Наиболее важные error codes

Auth

• INVALID_CREDENTIALS
• TOKEN_EXPIRED
• REFRESH_TOKEN_REVOKED
• ACCOUNT_BLOCKED
• ACCOUNT_UNDER_REVIEW
• PHONE_TAKEN
• EMAIL_TAKEN

Buyer

• BUYER_NOT_FOUND
• BUYER_ALREADY_EXISTS
• CHILD_NOT_FOUND
• MAX_CHILDREN_REACHED
• MAX_INTERESTS_EXCEEDED

Seller

• SELLER_NOT_FOUND
• SELLER_TYPE_IMMUTABLE
• MAX_ADDRESSES_REACHED
• CANNOT_DELETE_ONLY_ADDRESS
• TELEGRAM_ALREADY_BOUND

Uploads

• FILE_TOO_LARGE
• INVALID_FORMAT
• IMAGE_TOO_SMALL

7. Backward compatibility

• Legacy aliases могут существовать, но не считаются каноническим контрактом для новой разработки.
• Примеры: PUT /me/profile, PUT /seller/profile, старый POST /auth/register.
• Новые UI и интеграции должны строиться только на канонических маршрутах.
• Любой backend package, который вводит новый canonical path или меняет старый, обязан обновлять frontend-change-log.md.

8. Pagination, filters, search params

• Query params считаются частью transport contract.
• Пустые и неиспользуемые параметры не должны передаваться “на всякий случай”.
• Для публичного каталога canonical behavior нужно брать из OpenAPI и реального backend implementation, а не из старых frontend допущений.
• Любой change package, который меняет query/filter semantics, обязан обновлять api-routes.md и frontend changelog.

9. Upload conventions

• Image upload endpoint: POST /api/v1/upload/image
• Transport: multipart/form-data
• Имя поля файла: file
• Backend возвращает url как готовый публичный URL до загруженного объекта
• При local driver это обычно /uploads/images/<fileName>
• При s3/CDN driver это может быть абсолютный URL на bucket/CDN
• Клиент не должен самостоятельно придумывать storage URL в обход backend response

10. Временные и датовые правила

• Для API и тестов canonical timezone — UTC
• Все новые transport timestamps должны передаваться как ISO-8601 строки
• Серверные и тестовые сценарии, чувствительные ко времени, должны проверяться в TZ=UTC

11. Правило для frontend-команды

• Не поддерживать ручные transport types там, где endpoint уже описан в OpenAPI
• Не обходить generated contract layer без документированной причины
• Любой contract drift решается через backend artifact, а не локальным исправлением типов во frontend