2026-07-05 04:23:47 +04:00
|
|
|
|
# 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.
|
|
|
|
|
|
|
2026-07-09 00:45:36 +04:00
|
|
|
|
## Product Engagement API (ожидаемый контракт)
|
|
|
|
|
|
- GET /products/{id}/rating
|
|
|
|
|
|
- возвращает агрегированную оценку и распределение по звездам.
|
|
|
|
|
|
- GET /products/{id}/reviews
|
|
|
|
|
|
- поддерживает пагинацию (page/pageSize).
|
|
|
|
|
|
- GET /products/{id}/questions
|
|
|
|
|
|
- поддерживает пагинацию (page/pageSize).
|
|
|
|
|
|
- POST /products/{id}/reviews
|
|
|
|
|
|
- принимает rating/title/text/anonymous.
|
|
|
|
|
|
- POST /products/{id}/questions
|
|
|
|
|
|
- принимает text/anonymous.
|
|
|
|
|
|
|
|
|
|
|
|
Правило:
|
|
|
|
|
|
- Feature UI не вызывает API напрямую; запросы идут через ProductFacade -> domain service -> provider/repository.
|
|
|
|
|
|
|
2026-07-09 00:55:50 +04:00
|
|
|
|
## Advanced Catalog/Search Expectations
|
|
|
|
|
|
- Suggestions endpoint (future-ready):
|
|
|
|
|
|
- GET /search/suggestions?q={term}
|
|
|
|
|
|
- response: suggestion strings with optional popularity/count metadata.
|
|
|
|
|
|
- Dynamic filter metadata endpoint (future-ready):
|
|
|
|
|
|
- GET /catalog/filters?category={id}&q={term}
|
|
|
|
|
|
- response: filter definitions/options that frontend can render without hardcoded filter schema.
|
|
|
|
|
|
- Sort extension contract:
|
|
|
|
|
|
- Backend may introduce new sort IDs via bootstrap `catalog.availableSorts`.
|
|
|
|
|
|
- Frontend must render unknown sort keys safely if label mapping is provided.
|
|
|
|
|
|
|
2026-07-05 04:23:47 +04:00
|
|
|
|
## Пример 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 данные.
|
|
|
|
|
|
- Поддерживать фильтрацию, пагинацию и сортировку для каталога.
|
