#Connector API

#Overview

После интеграции инструментов в кластере для текущего Коннектора может быть предоставлен RESTful API, позволяющий удобно получать ресурсы из инструмента. Эти API единообразно экспонируются через Connector API, что позволяет пользователям получать ресурсы из инструмента, на который указывает текущий Коннектор.

Система Коннекторов поддерживает два способа доступа к ресурсам инструмента через API:

• Оригинальный API инструмента: доступ к оригинальному API инструмента через Proxy Service
• Пользовательский API: использование пользовательского API, предоставленного для ConnectorClass

При использовании Connector API клиентам не нужно управлять оригинальными учетными данными инструмента. Им достаточно иметь права на доступ к Коннектору. Права на запросы API к инструменту определяются правами учетных данных (Secret), настроенных в Коннекторе.

#Адрес и аутентификация Connector API

#Адрес API

Адрес Connector API состоит из трёх частей:

• Точка входа доступа к Platform API или ingress кластера
• Относительный путь Connector API
• Путь к оригинальному API запрашиваемого инструмента или пользовательскому API

После создания Коннектора в кластере, Коннектор автоматически записывает путь API текущего Коннектора в <connector>.status.api.path. Обратите внимание, что этот путь является относительным относительно точки входа доступа к кластеру.

Итоговый адрес Connector API: {platform_api_address}/{<connector>.status.api.path}/{api-path}

#Аутентификация и авторизация

Аутентификация соответствует стандартам Kubernetes и осуществляется через механизмы аутентификации и авторизации Kubernetes. Запрашивающий пользователь должен иметь права на чтение соответствующего Connector. В настоящее время поддерживается только аутентификация с использованием Bearer Token.

При выполнении конечного запроса к инструменту для аутентификации используется информация из Secret, указанного в Коннекторе.

Для получения дополнительной информации об аутентификации в Kubernetes см. Kubernetes Authentication documentation.

#Доступ к оригинальному API инструмента

Если ваш ConnectorClass предоставляет возможности Proxy Service, вы можете напрямую обращаться к оригинальному API инструмента через Connector API.

Например, если оригинальный адрес API инструмента — /api/v4/projects, вы можете получить к нему доступ через Connector API. Предположим, что у вас есть Коннектор с именем gitlab-connector в пространстве имён default, а путь API Коннектора — /connectors/v1alpha1/default/gitlab-connector/path. Тогда запрос будет выглядеть так:

K8S_TOKEN=xxxx

curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/gitlab-connector/path/api/v4/projects"

Возможности Proxy Service настраиваются через спецификацию ConnectorClass. Подробности настройки см. в разделе ConnectorClass Proxy. Для более глубокого понимания концепции Connectors Proxy обратитесь к Connectors Proxy.

#Пользовательский API

Если оригинальный API инструмента не удовлетворяет вашим требованиям или ConnectorClass не предоставляет возможности Proxy Service, вы можете предоставить пользовательский API-сервис для текущего ConnectorClass, чтобы удовлетворить ваши потребности.

Пользовательский API-сервис настраивается через поле spec.api ConnectorClass, что позволяет системе Коннекторов обнаруживать и использовать его. Подробности настройки см. в разделе ConnectorClass API.

Кроме того, чтобы система могла определить, что API является пользовательским, необходимо настроить описание OpenAPI через поле spec.api.openapi.

#Определение API

#Путь API

Путь API, предоставляемый пользовательским API, может свободно определяться в расширенном API-сервисе. Рекомендуемый формат — /<connectorclass-name>/xxx.

В сочетании с адресом API и аутентификацией, описанными выше, пример запроса выглядит так. Предположим, что у вас есть Коннектор с именем git-connector в пространстве имён default, а путь пользовательского API — /git/gitrefs. Тогда запрос будет:

K8S_TOKEN=xxxx

curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/git-connector/path/git/gitrefs"

#Параметры запроса

Параметры запроса определяются конкретной спецификацией API ConnectorClass.

#Пагинация

Информация о пагинации указывается через параметры запроса:

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

При возврате списка структура ответа следующая:

{
    "listMeta":{
        "totalItems":0
    },
    "items": [
        {

        }
    ]
}

Если ответ не 200, возвращаемая структура данных должна соответствовать k8s status.

Например:

{
    "status": "Failure",
    "message": "api address of connectorclass 'git-noapi' is not resolved",
    "reason": "BadRequest",
    "code": 400,
    "details": null
}

Определения полей и значения перечислений совпадают с k8s status.

#Описание OpenAPI

Помимо предоставления пользовательского API-сервиса, необходимо настроить описание OpenAPI в поле spec.api.openapi ConnectorClass, чтобы система могла определить, что API является пользовательским.

Пример:

kind: ConnectorClass
metadata:
  name: gitlab
spec:
  api:
    ref:  # Ссылка на сервис пользовательского API
      name: connectors-gitlab-api
      namespace: connectors-system
    openapi:
      openapi: "3.0.1"
      info:
        title: GitLab Custom API
        version: "1.0.0"
      paths:
        /gitlab/custom-api:  # Пользовательский API, определённый в сервисе connectors-gitlab-api
          get:
            x-provider-type: api  # Указывает, что этот API является пользовательским
            summary: Запрос пользовательского API
            responses:
              "200":
                description: Ответ пользовательского API

Система автоматически перенаправит пользовательский API на адрес API ConnectorClass на основе описания spec.api.openapi.

Подробности настройки spec.api.openapi см. в разделе ConnectorClass OpenAPI Description. Для дополнительных примеров использования обратитесь к Using Connectors API in Dynamic Forms.

#Спецификация расширения API ConnectorClass

Разработчики могут расширять возможности API для ConnectorClass, предоставляя пользователям более богатые возможности получения ресурсов.

См. ConnectorClass API Extension Specification.

#Использование Connectors API в динамических формах

Connector API может быть предоставлен UI-клиентам, особенно в сценариях динамических форм, где UI-клиенты могут гибко настраивать вызываемые API-запросы.

Для этого необходимо настроить описание OpenAPI через поле spec.api.openapi ConnectorClass, которое совместно с DSL динамической формы реализует динамическую отрисовку форм на фронтенде.

Описание динамической формы обычно предоставляется в Resource Interface. Подробнее см. в разделе Resource Interface.