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

Справочник по базовым API бета-версии КАСКАД 360. Авторизация, работа с БД, маршрутизация.

Содержание

Бета-версия API. Все эндпоинты стабильны, но могут быть расширены в последующих версиях. Обратная совместимость гарантируется в рамках мажорной версии.

1. Обзор API

API КАСКАД 360 — это RESTful API, доступный по базовому URL сервера. Все запросы и ответы используют формат JSON.

Базовые URL

Тип установкиURL
Локальная (Python)http://localhost:5000
Docker Composehttp://localhost:3535

Общие заголовки

Content-Type: application/json
Authorization: Bearer <JWT_TOKEN>

Формат ответа

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

// При ошибке:
{
  "success": false,
  "error": "описание ошибки",
  "code": "ERROR_CODE"
}

2. Авторизация

Бета-версия поддерживает два метода авторизации: JWT-токены и API-ключи.

2.1. Получение JWT-токена

POST /api/v1/auth/login

Авторизация по логину и паролю. Возвращает JWT-токен.

Тело запроса

{
  "username": "admin",
  "password": "admin"
}

Успешный ответ (200)

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600,
    "user": {
      "id": 1,
      "username": "admin",
      "role": "admin"
    }
  }
}

2.2. Использование API-ключа

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

X-API-Key: your-api-key-here

2.3. RBAC (роли)

РольОписаниеДоступ
adminАдминистраторПолный доступ
managerМенеджерУправление сервисами, просмотр метрик
developerРазработчикAPI к БД, конфигурация маршрутов
viewerНаблюдательТолько чтение

3. Чтение данных из БД

Без SQL. Все запросы к БД выполняются через параметризованный API. Ядро само формирует SQL через ORM/QueryBuilder. Передача сырого SQL запрещена.

POST /api/v1/db/query

Чтение данных из таблицы/сущности.

Тело запроса

{
  "entity": "products",
  "fields": ["id", "name", "price", "category"],
  "filters": {
    "category": "electronics",
    "price": {"$gte": 1000}
  },
  "order": [{"field": "price", "dir": "desc"}],
  "limit": 20,
  "offset": 0,
  "datasource_id": "main"
}

Параметры

ПараметрТипОбязательныйОписание
entitystringдаИмя таблицы/сущности (из whitelist)
fieldsarrayнетСписок полей для выборки. По умолчанию — все
filtersobjectнетУсловия фильтрации (key-value или операторы)
orderarrayнетСортировка: [{"field": "...", "dir": "asc|desc"}]
limitintegerнетМакс. количество записей (по умолчанию 100)
offsetintegerнетСмещение для пагинации
datasource_idstringнетИдентификатор подключения к БД

Операторы фильтрации

ОператорОписаниеПример
$eqРавно (по умолчанию){"status": "active"}
$neНе равно{"status": {"$ne": "deleted"}}
$gt, $gteБольше / Больше или равно{"price": {"$gte": 100}}
$lt, $lteМеньше / Меньше или равно{"age": {"$lt": 30}}
$inВходит в список{"id": {"$in": [1, 2, 3]}}
$likeПоиск по шаблону{"name": {"$like": "%каскад%"}}

Успешный ответ (200)

{
  "success": true,
  "data": {
    "items": [
      {"id": 5, "name": "Ноутбук", "price": 89000, "category": "electronics"},
      {"id": 12, "name": "Монитор", "price": 35000, "category": "electronics"}
    ],
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

4. Запись данных в БД

4.1. Создание записи

POST /api/v1/db/execute

Тело запроса

{
  "entity": "products",
  "action": "create",
  "data": {
    "name": "Новый товар",
    "price": 15000,
    "category": "electronics",
    "description": "Описание товара"
  }
}

Успешный ответ (201)

{
  "success": true,
  "data": {
    "id": 55,
    "affected_rows": 1
  }
}

4.2. Обновление записей

POST /api/v1/db/execute 
{
  "entity": "products",
  "action": "update",
  "data": {
    "price": 12000,
    "description": "Обновлённое описание"
  },
  "filters": {
    "id": 55
  }
}

4.3. Удаление записей

POST /api/v1/db/execute 
{
  "entity": "products",
  "action": "delete",
  "filters": {
    "id": 55
  }
}

Осторожно: удаление без filters запрещено. Ядро возвращает ошибку FILTERS_REQUIRED.

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

Для выполнения нескольких операций атомарно используйте транзакции.

5.1. Начать транзакцию

POST /api/v1/db/transaction/begin 
// Ответ
{
  "success": true,
  "data": {
    "transaction_id": "txn_abc123def456"
  }
}

5.2. Выполнить операцию в транзакции

// Добавьте transaction_id к любому запросу
{
  "entity": "orders",
  "action": "create",
  "data": { "user_id": 1, "total": 5000 },
  "transaction_id": "txn_abc123def456"
}

5.3. Подтвердить / откатить

POST /api/v1/db/transaction/commit 
{
  "transaction_id": "txn_abc123def456"
}
POST /api/v1/db/transaction/rollback 
{
  "transaction_id": "txn_abc123def456"
}

6. Сервисы и маршрутизация

Шлюз автоматически проксирует запросы к зарегистрированным сервисам на основе маршрутов.

6.1. Список сервисов

GET /api/v1/services

Возвращает список зарегистрированных сервисов.

{
  "success": true,
  "data": [
    {
      "name": "backend-api",
      "host": "localhost",
      "port": 8080,
      "status": "healthy",
      "routes": ["/api/v1/users/*", "/api/v1/orders/*"]
    }
  ]
}

6.2. Состояние сервиса

GET /api/v1/services/{name}/health

Проверка здоровья конкретного сервиса.

{
  "success": true,
  "data": {
    "name": "backend-api",
    "status": "healthy",
    "latency_ms": 12,
    "last_check": "2026-06-01T10:30:00Z"
  }
}

6.3. Проксирование запросов

Все запросы, совпадающие с маршрутами сервиса, автоматически проксируются:

# Этот запрос будет проксирован на backend-api (localhost:8080)
curl http://localhost:5000/api/v1/users/42 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Шлюз перенаправит на http://localhost:8080/api/v1/users/42

7. Административный API

Для программного управления шлюзом (требуется роль admin или manager).

GET /api/v1/admin/status

Общий статус шлюза.

{
  "success": true,
  "data": {
    "version": "1.0.0-beta",
    "uptime_seconds": 86400,
    "services_count": 3,
    "active_connections": 12,
    "plugins": ["auth", "security", "validation"]
  }
}
GET /api/v1/admin/routes

Список всех маршрутов.

GET /api/v1/admin/datasources

Список подключений к базам данных.

GET /api/v1/admin/plugins

Список загруженных плагинов.

8. Коды ошибок

HTTPКодОписание
400INVALID_REQUESTНекорректные параметры запроса
400ENTITY_NOT_ALLOWEDСущность не в whitelist
400FILTERS_REQUIREDФильтры обязательны для update/delete
401UNAUTHORIZEDТребуется авторизация
401TOKEN_EXPIREDJWT-токен истёк
403FORBIDDENНедостаточно прав (RBAC)
404NOT_FOUNDРесурс не найден
429RATE_LIMITEDПревышен лимит запросов
500INTERNAL_ERRORВнутренняя ошибка сервера
502SERVICE_UNAVAILABLEЦелевой сервис недоступен

9. Ограничения бета-версии

ПараметрСтарт (бета)ПроБизнес
Сервисыдо 2до 10до 50
Подключения к БД1до 5Без ограничений
Драйверы БДMySQL или PostgreSQLMySQL + PostgreSQLMySQL + PostgreSQL
Service DiscoveryStaticStatic + DockerDocker, K8s, Consul, etcd
БалансировкаНет3 алгоритма5 алгоритмов + автомасштабирование
МониторингБазовый (логи)PrometheusPrometheus, Grafana, ELK, OpenTelemetry
БезопасностьJWT, API Keys, RBAC+ кэш, трансформация+ MFA, WAF, DDoS
Плагины3 (auth, security, validation)5+ (+ кэш, трансформация)Все
Админ-панельБазоваяРасширеннаяДинамическая (от модулей)
Файловое хранилищеНетНетДа
SLA / ПоддержкаДокументацияEmail99.5%, телефон

Бета-версия предназначена для тестирования и раннего внедрения. По вопросам расширения функционала — свяжитесь с нами.

Инструкция по установке Получить ранний доступ