From f804a09c9f382f77b077039c9f58595ceeac8cd2 Mon Sep 17 00:00:00 2001
From: Georgii Zhulikov <gzhulikov@hse.ru>
Date: Mon, 2 Jun 2025 15:22:35 +0300
Subject: [PATCH] API component draft

---
 pages/api-component.md | 114 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 pages/api-component.md

diff --git a/pages/api-component.md b/pages/api-component.md
new file mode 100644
index 0000000..7c72059
--- /dev/null
+++ b/pages/api-component.md
@@ -0,0 +1,114 @@
+# Настройка доступа к компонентам модуля через API
+
+Чтобы внешние пользователи могли использовать компоненты приложения - запускать расчёты в ML-компонентах и пайплайнах, работать с файлами в DataBox - нужно добавить в приложение соответствующие API-компоненты.
+
+Это могут быть:
+
+- API для работы с файлами.
+- API для работы с пайплайнами и их запусками в общем.
+- API для работы с одним конкретным ML-компонентом.
+- API для работы с одним конкретным пайплайном.
+
+## Общий шаблон API-компонента
+
+```yaml
+apiVersion: "unified-platform.cs.hse.ru/v1"
+kind: APIComponent
+metadata:
+  name: my-api
+  namespace: pu-username-pa-appname
+spec:
+  published: true
+  # <вид API>
+  restfulApi:
+    auth:
+      basic:
+        credentials: appname-apis-cred
+      identityPassThrough: true
+```
+
+Здесь,
+
+- `metadata.name` - имя API-компонента, должно быть уникальным среди API-компонентов в одном модуле
+- `metadata.namespace` - полное название приложение
+- `spec.published` - "включен" ли API - возможно добавить API-компонент, но временно его "выключить" - тогда запросы к нему не будут работать.
+- `spec.restfulAPI` - раздел настроек доступа. Поддерживается базовая авторизация и Open ID Connect.
+
+## Вид API-компонента
+
+Выше в шаблоне комментарий "<вид API>" должен быть заменён одной из секций ниже в зависимости от типа API-компонента.
+
+### Файловый APi
+
+```yaml
+  files:
+    enabled: true
+```
+
+### API для пайплайнов в целом
+
+```yaml
+  pipelines:
+    enabled: true
+```
+
+### API для ML-компонента
+
+Помимо вида API, в раздел `restfulApi` нужно добавить путь, по которому будет осуществляться доступ к модулю.
+
+```yaml
+  mlComponent:
+    name: my-mlcmp
+  restfulApi:
+    path: image
+    auth:
+```
+
+Здесь `mlComponent.name` - это имя компонента `MLComponent`, а `restfulApi.path` - путь, который нужно указывать в URL в запросах к ML-компоненту.
+
+Например, манифесту выше соответствует ссылка для запуска расчётов `https://platform.stratpro.hse.ru/pu-username-pa-appname/image/predict`.
+
+
+### API для конкретного пайплайна
+
+```yaml
+  experimentPipeline:
+    name: my-pipeline
+```
+
+Если в API-компоненте указан раздел `experimentPipeline`, то в таком компоненте обязательно должен присутствовать раздел `spec.apiSpec` со спецификацией интерфейса конкретного пайплайна.
+
+Подробнее - в разделе [о пайплайнах](./pipeline.md).
+
+## Авторизация/аутентификация
+
+В шаблоне выше приведён пример Basic авторизации. В таком случае используется набор реквизитов, который присутствует в модуле. В данном случае, реквизиты хранятся в компоненте `appname-apis-cred`.
+
+Помимо базовой авторизации можно использовать OIDC. Для этого в раздел `spec.restfulApi.auth` нужно добавить поле `oidc`.
+
+Пример:
+
+```yaml
+apiVersion: "unified-platform.cs.hse.ru/v1"
+kind: APIComponent
+metadata:
+  name: my-api
+  namespace: pu-username-pa-appname
+spec:
+  published: true
+  files:
+    enabled: true
+  restfulApi:
+    auth:
+      identityPassThrough: true
+      oidc: {}
+        # groups: ["/dev-multi-auth"]
+        # enabled: false # default - true
+        # roles: ["/test"]
+```
+
+В самом простом случае поле `oidc` можно оставить пустым словарём - `oidc: {}`. Также можно контролировать настройки OIDC:
+
+- `groups` - список разрешённых групп
+- `roles` - список разрешённых ролей
+- `enabled` - включена ли OIDC аутентификация (по умолчанию включена, указанием этого пункта можно выключить)