Структура API: пути и область

Как читать пути OpenAPI и понимать контекст запроса.

Ниже — карта HTTP API Shturval Backend API по файлу OpenAPI (swagger.json): как устроены префиксы путей, что означает параметр cluster_id, чем отличаются «платформенные» и «кластерные» сценарии, зачем нужен раздел /tenants, где смотреть WebSocket.

Базовый путь и транспорт #

• В спецификации задано поле basePath: /api/v1. Итоговый URL REST-операции: {scheme}://{хост}/api/v1{path}, где path из колонки Swagger (например, /clusters, /platform/version).
• Для schemes в спецификации указаны http и https — в продуктиве обычно используется HTTPS.

Раздел /clusters и вложенные пути #

• Префикс /clusters — операции в разрезе кластеров: список кластеров, сведения по cluster_id, kubeconfig, ресурсы неймспейсов, сети, политики, observability и т.д.
• /clusters/{cluster_id}/namespaces/{namespace_name}/...: запросы в контексте конкретного кластера и неймспейса (согласуется с моделью «кластер → неймспейс → объект»).
• Сценарии создания и жизненного цикла кластеров (провижининг, шаблоны) дополнительно разобраны в документации: API для управления кластерами.

Раздел /platform #

• Префикс /platform объединяет глобальные для установки платформы настройки и операции: аутентификация (например, LDAP, OIDC), провайдеры и интеграции, профили, разрешения и роли, сессии, лицензия, сведения о версии, списки kubeconfig’ов, UI permissions и т.п.
• Путь /platform/swag в спецификации относится к служебной выдаче/обёртке спецификации (см. описание в Swagger). Пользовательский обзор открытия UI Swagger описан в разделе про Swagger.

Раздел /tenants #

• Префикс /tenants — операции в модели тенантов (создание, атрибуты), если мультитенантность задействована в вашей среде.

WebSocket и интерактивные сценарии #

Помимо REST, в OpenAPI присутствуют пути под /websocket/...: например, поток логов контейнера и терминал. Это не обычные GET/POST с JSON-телом в одном ответе — клиенту нужен WebSocket-клиент (как в UI или в специализированных утилитах).

Смотрите требования к аутентификации/парам для каждой такой операции в Swagger на соответствующем пути.

Как сопоставить путь в Swagger и «куда нажимать в UI» #

1. В Swagger найдите path (например, /platform/providers).
2. Убедитесь, что у метода в блоке security указан Bearer .
3. Соберите итоговый URL: {BACKENDPOINT}/api/v1 + path из шага 1, подставив параметры пути (cluster_id, namespace_name и т.д.).

Авторизация по токену: Авторизация и токен.