Документация API

1. Обзор публичного API

КАСКАД 360 предоставляет HTTP JSON API для подключения внешних приложений, мобильных клиентов и сервисов. Ядро не требует сессии администратора для публичных маршрутов — доступ контролируется API-ключами или JWT-токенами с ограниченными правами.

Базовый URL

Группы публичного API

* Бэкенд-сервис может реализовать собственную авторизацию для бизнес-логики.

Типовой формат ответа

{
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": "Описание ошибки"
}

Интерактивная спецификация

На развёрнутом экземпляре доступны:

• API Explorer (рекомендуется): http://localhost:5000/admin/api-explorer — Admin и Public API, фильтры (ядро / модуль / плагин / сервис), Try it out с RBAC, экспорт OpenAPI (требует входа в админку).
• Публичный Swagger UI: http://localhost:5000/api/docs/public — только Public API; на странице есть напоминание об API Explorer в админке.
• OpenAPI JSON: http://localhost:5000/api/openapi.json

Legacy-адрес /api/v1/admin/docs перенаправляет в API Explorer.

2. Аутентификация

Для публичного API используются два механизма. Сессия администратора (cookie после входа в панель) в интеграциях не применяется.

2.1. API-ключ

Ключ выдается администратором платформы в разделе управления API-ключами. Передавайте его в заголовке или query-параметре:

X-API-Key: your-api-key

# альтернатива
GET /api/v1/db/datasources?api_key=your-api-key

Ключ содержит набор разрешений. Для работы с БД нужны db:query или db:*; для файлов — files:upload, files:download или files:*.

2.2. JWT-токен (для API файлов)

Для сценариев, где файлы связаны с учётной записью пользователя, используйте JWT access token в заголовке:

Authorization: Bearer <access_token>

Токены выдаются по учётным данным пользователя:

{
  "username": "user@example.com",
  "password": "your-password"
}

Обновление access token:

POST /api/v1/admin/auth/token/refresh
{ "refresh_token": "..." }

3. API доступа к БД (/api/v1/db/*)

3.1. Выполнение запроса

Выборка (select)

{
  "entity": "products",
  "action": "select",
  "fields": ["id", "name", "price"],
  "filters": [
    {"field": "status", "op": "eq", "value": "active"},
    {"field": "price", "op": "gte", "value": 100, "boolean": "and"}
  ],
  "sort": [{"field": "id", "direction": "desc"}],
  "limit": 50,
  "offset": 0,
  "datasource_id": "core",
  "database": "shop"
}

Вставка (insert)

{
  "entity": "orders",
  "action": "insert",
  "data": {"user_id": 42, "total": 1500},
  "datasource_id": "core",
  "database": "shop"
}

Обновление и удаление

Для update и delete поле filters обязательно — операции без условий отклоняются.

{
  "entity": "orders",
  "action": "update",
  "data": {"status": "shipped"},
  "filters": [{"field": "id", "op": "eq", "value": 1001}],
  "datasource_id": "core",
  "database": "shop"
}

Поддерживаемые операторы фильтров (op)

Пример ответа

{
  "success": true,
  "data": [
    {"id": 1, "name": "Товар", "price": 199}
  ],
  "row_count": 1
}

3.2. Транзакции

Для группы связанных изменений используйте транзакции. transaction_id передаётся в последующие вызовы /query.

3.3. Источники данных

4. API файлов (/api/v1/files/*)

Загрузка и получение файлов через платформу. Авторизация: API-ключ с правами files:* или JWT access token.

4.1. Загрузка

curl -X POST http://localhost:5000/api/v1/files/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@document.pdf" \
  -F "category=documents" \
  -F "is_public=false"

4.2. Метаданные файла

4.3. Скачивание

5. Модульная маршрутизация (/api/module/*)

Единая точка входа для запросов к подключённым бэкенд-сервисам. Ядро резолвит модуль через правила маршрутизации и проксирует HTTP-запрос к целевому сервису.

Формат URL

/api/module/<module>/<method>

# пример
GET /api/module/back/products
POST /api/module/back/orders/create

Параметры query, заголовки и тело запроса передаются к бэкенду. Авторизация на уровне ядра не требуется — сервис может реализовать собственную проверку токенов или ключей.

Пример

curl -X GET "http://localhost:5000/api/module/back/products?limit=10" \
  -H "Content-Type: application/json"

6. Служебные endpoints

Не требуют аутентификации. Используются для health-check и мониторинга доступности.

7. Коды ответов и ошибки

{
  "success": false,
  "error": "Текст ошибки",
  "details": { ... }
}

По умолчанию действует rate limiting: около 60 запросов в минуту и 1000 в час на ключ. При превышении в ответе может присутствовать поле retry_after.

8. Версия и ограничения