Документация API — КАСКАД 360

Содержание

1. Обзор API версии 1.0.2
2. Аутентификация и доступ
3. Внешний API БД (/api/v1/db/*)
4. Админ API БД (/api/base/db/*)
5. Управление сервисами
6. Маршрутизация, плагины и мониторинг
7. Настройка и служебные API
8. Коды ответов и формат ошибок
9. Версия и совместимость

Документация для версии 1.0.2. Ниже указаны маршруты, которые реально зарегистрированы в этой версии проекта.

1. Обзор API версии 1.0.2

КАСКАД 360 использует HTTP JSON API с разделением на внешний и административный контуры. Основной порт приложения в текущем конфиге: 5000.

Базовые URL

Контур	Базовый URL	Назначение
Основной сервер	`http://localhost:5000`	Админ API, внешний API БД, UI
Docker Compose (если настроен в окружении)	`http://localhost:3535`	Проксируемый порт контейнера

Группы API

Префикс	Доступ	Назначение
`/api/v1/admin/*`	Сессия (cookie) после входа	Управление системой, сервисами, плагинами, мониторинг
`/api/v1/db/*`	API-ключ (`X-API-Key`)	Внешний доступ к БД и транзакциям
`/api/base/*`	Сессия администратора	Системные и административные операции

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

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

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

2. Аутентификация и доступ

2.1. Сессионная авторизация для админ API

POST /api/v1/admin/auth/login

Выполняет вход и устанавливает сессионную cookie. Используется для /api/v1/admin/* и /api/base/*.

{
  "username": "admin",
  "password": "your-password",
  "mfa_code": "123456"
}

POST /api/v1/admin/auth/logout

Завершает текущую сессию.

GET /api/v1/admin/auth/me

Возвращает данные текущего авторизованного пользователя.

2.2. API-ключ для внешнего API БД

Для /api/v1/db/* применяется API-ключ в заголовке или query-параметре.

X-API-Key: your-api-key

# либо
GET /api/v1/db/datasources?api_key=your-api-key

2.3. JWT endpoints (дополнительно)

В системе также доступны маршруты выдачи и обновления JWT:

POST /api/v1/admin/auth/token
POST /api/v1/admin/auth/token/refresh
POST /api/v1/admin/auth/token/revoke

Базовый административный доступ по умолчанию построен на сессии.

3. Внешний API БД (/api/v1/db/*)

Назначение: интеграции и внешние сервисы. Все маршруты ниже требуют API-ключ с правами db:query или db:*.

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

POST /api/v1/db/query

Поддерживает два режима: параметризованный контракт (entity + action) и legacy SQL (query).

Параметризованный режим (рекомендуется)

{
  "entity": "users",
  "action": "select",
  "fields": ["id", "username", "email"],
  "filters": [{"field": "is_admin", "op": "eq", "value": 1}],
  "limit": 50,
  "offset": 0,
  "datasource_id": "core"
}

Legacy SQL режим

{
  "query": "SELECT id, username FROM users WHERE is_admin = %s",
  "params": [1],
  "datasource_id": "core"
}

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

Метод	Путь	Назначение
POST	`/api/v1/db/transaction/begin`	Создать транзакцию
POST	`/api/v1/db/transaction/<transaction_id>/commit`	Подтвердить транзакцию
POST	`/api/v1/db/transaction/<transaction_id>/rollback`	Откатить транзакцию
GET	`/api/v1/db/transaction/list`	Список активных транзакций

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

GET /api/v1/db/datasources

Возвращает список доступных datasource без секретов.

4. Админ API БД (/api/base/db/*)

Эти маршруты используются админ-панелью после входа в систему.

Метод	Путь	Назначение
GET	`/api/base/db/tables`	Список таблиц
GET	`/api/base/db/table/<table_name>`	Данные таблицы (пагинация)
GET	`/api/base/db/table/<table_name>/structure`	Структура таблицы
POST	`/api/base/db/table/<table_name>/row`	Добавить строку
PATCH	`/api/base/db/table/<table_name>/row/<pk>`	Изменить строку
DELETE	`/api/base/db/table/<table_name>/row/<pk>`	Удалить строку
GET/POST	`/api/base/db/config`	Чтение и сохранение конфигурации БД
POST	`/api/base/db/test`	Проверка соединения с БД

5. Управление сервисами

Основные маршруты управления сервисами находятся в пространстве /api/v1/admin/services/*.

GET /api/v1/admin/services/list

Список сервисов с фильтрами search, status, environment, tags.

Метод	Путь	Назначение
GET	`/api/v1/admin/services/<service_name>/status`	Статус сервиса
GET	`/api/v1/admin/services/<service_name>/metrics`	Метрики сервиса
GET	`/api/v1/admin/services/<service_name>/info`	Расширенная информация
POST	`/api/v1/admin/services/<service_name>/restart`	Перезапуск
POST	`/api/v1/admin/services/<service_name>/start`	Запуск
POST	`/api/v1/admin/services/<service_name>/stop`	Остановка
POST	`/api/v1/admin/services/<service_name>/scale`	Масштабирование реплик
POST	`/api/v1/admin/services/<service_name>/health-check`	Принудительный health-check

6. Маршрутизация, плагины и мониторинг

6.1. Маршрутизация

Метод	Путь	Назначение
GET	`/api/v1/admin/routing/rules`	Список правил
POST	`/api/v1/admin/routing/rules`	Создать правило
DELETE	`/api/v1/admin/routing/rules/<rule_index>`	Удалить правило
POST	`/api/v1/admin/routing/preview`	Предпросмотр маршрута
POST	`/api/v1/admin/routing/reload`	Hot-reload правил
GET	`/api/v1/admin/routing/history`	История изменений

6.2. Плагины

Метод	Путь	Назначение
GET	`/api/v1/admin/plugins`	Список плагинов
POST	`/api/v1/admin/plugins/<plugin_name>/load`	Загрузить и запустить
POST	`/api/v1/admin/plugins/<plugin_name>/unload`	Выгрузить
POST	`/api/v1/admin/plugins/<plugin_name>/start`	Запустить
POST	`/api/v1/admin/plugins/<plugin_name>/stop`	Остановить
GET/POST	`/api/v1/admin/plugins/<plugin_name>/config`	Конфигурация плагина

6.3. Мониторинг

Маршруты мониторинга доступны в /api/v1/admin/monitoring/*.

Метод	Путь
GET	`/api/v1/admin/monitoring/metrics/summary`
GET	`/api/v1/admin/monitoring/metrics/history`
GET	`/api/v1/admin/monitoring/alerts`
POST	`/api/v1/admin/monitoring/alerts/rules`
GET	`/api/v1/admin/monitoring/traces`

7. Настройка и служебные API

7.1. API первичной настройки (до завершения setup)

Метод	Путь	Назначение
GET/POST	`/api/db/config`	Конфигурация БД мастера установки
POST	`/api/db/test`	Проверка соединения с БД
GET	`/api/admin/check`	Проверка наличия администратора
POST	`/api/admin/create`	Создание администратора
GET/POST	`/api/app/settings`	Настройки приложения
POST	`/api/setup/complete`	Завершение установки

7.2. Центр обновлений (новое в 1.0.2)

В версии 1.0.2 добавлен API центра обновлений для управления релизами ядра, модулей и плагинов из админ-панели.

Метод	Путь	Назначение
GET	`/api/v1/admin/updates/config`	Текущая конфигурация updates
GET	`/api/v1/admin/updates/check`	Проверка доступных обновлений
GET	`/api/v1/admin/updates/catalog`	Каталог артефактов и совместимость
POST	`/api/v1/admin/updates/install`	Создание задачи установки модуля/плагина
POST	`/api/v1/admin/updates/core`	Создание задачи обновления ядра
POST	`/api/v1/admin/updates/rollback`	Создание задачи отката
GET	`/api/v1/admin/updates/jobs`	Список задач обновления
GET	`/api/v1/admin/updates/readiness`	Readiness-проверка production rollout

7.3. Дополнительные служебные endpoints

В приложении также доступны служебные маршруты для метрик, файлов, модулей, лицензий, контейнеров и CRM в пространстве /api/v1/admin/*, /api/v1/files/*, /crm и /api/crm/*.

8. Коды ответов и формат ошибок

HTTP	Когда используется
200	Успешный запрос
400	Ошибка валидации или параметров
401	Нет сессии или неверный API-ключ
403	Недостаточно прав (role/permission/beta-ограничения)
404	Ресурс не найден
500	Внутренняя ошибка
503	Внешний сервис/конфиг недоступен

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

9. Версия и совместимость

Параметр	Текущее значение проекта
Версия ядра	`1.0.2`
Основной API-префикс	`/api/v1`
Модель админ-доступа	Сессия + role/permissions
Внешний доступ к БД	API-ключ (`X-API-Key`)
WebSocket	`/ws` (при включении в конфиге)

Для детальной установки и запуска используйте инструкцию по установке. Если нужна интеграция под ваш сценарий, отправьте запрос через форму связи.

Инструкция по установке Отправить обратную связь