marketplaces/docs/platform/06-api-contracts.md

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 ответа: категории

{
  "data": [
    {
      "id": 101,
      "title": "Смартфоны",
      "parentId": null,
      "priority": 1,
      "visible": true
    }
  ],
  "meta": {
    "total": 1
  }
}

Пример API ответа: товары

{
  "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 данные.
• Поддерживать фильтрацию, пагинацию и сортировку для каталога.