# Настройка доступа к компонентам модуля через 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 аутентификация (по умолчанию включена, указанием этого пункта можно выключить)