75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
|
# 06. API-контракты
|
|||
|
|
|
|||
|
|
## Назначение
|
|||
|
|
Документ определяет стабильные контракты API для данных маркетплейса. Backend предоставляет только данные, frontend отвечает за представление.
|
|||
|
|
|
|||
|
|
## Поведение системы
|
|||
|
|
- API base URL определяется tenant-конфигурацией.
|
|||
|
|
- Frontend отправляет запросы через единый API слой и интерсепторы.
|
|||
|
|
- Ответы маппятся в доменные модели frontend.
|
|||
|
|
|
|||
|
|
## Обязательные свойства JSON (ответы API)
|
|||
|
|
- status или корректный HTTP status code
|
|||
|
|
- data (основная полезная нагрузка)
|
|||
|
|
- id для доменных сущностей
|
|||
|
|
|
|||
|
|
## Опциональные свойства JSON
|
|||
|
|
- meta (pagination, total, filters)
|
|||
|
|
- errors (детализация ошибок)
|
|||
|
|
- warnings
|
|||
|
|
|
|||
|
|
## Строгие правила
|
|||
|
|
- Backend не должен отдавать HTML для витрины.
|
|||
|
|
- Контракты должны быть обратно совместимы в пределах одной major-версии.
|
|||
|
|
- В ответах на списки должна поддерживаться пагинация.
|
|||
|
|
- Ошибки API должны быть машиночитаемыми и локализуемыми на frontend.
|
|||
|
|
|
|||
|
|
## Пример API ответа: категории
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": 101,
|
|||
|
|
"title": "Смартфоны",
|
|||
|
|
"parentId": null,
|
|||
|
|
"priority": 1,
|
|||
|
|
"visible": true
|
|||
|
|
}
|
|||
|
|
],
|
|||
|
|
"meta": {
|
|||
|
|
"total": 1
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Пример API ответа: товары
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"data": {
|
|||
|
|
"items": [
|
|||
|
|
{
|
|||
|
|
"itemID": 5001,
|
|||
|
|
"name": "Phone X",
|
|||
|
|
"price": 49990,
|
|||
|
|
"currency": "RUB",
|
|||
|
|
"categoryID": 101,
|
|||
|
|
"visible": true
|
|||
|
|
}
|
|||
|
|
],
|
|||
|
|
"total": 1,
|
|||
|
|
"skip": 0,
|
|||
|
|
"count": 20
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Ответственность Frontend
|
|||
|
|
- Маппинг API DTO в доменные модели.
|
|||
|
|
- Центральная обработка ошибок и retry-стратегий.
|
|||
|
|
- Кеширование и переиспользование данных без нарушения актуальности.
|
|||
|
|
|
|||
|
|
## Ответственность Backend
|
|||
|
|
- Гарантировать SLA и стабильность контрактов.
|
|||
|
|
- Возвращать tenant-correct данные.
|
|||
|
|
- Поддерживать фильтрацию, пагинацию и сортировку для каталога.
|