#Connector API

#Overview

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

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

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

При использовании Connectors 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 API см. 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, что позволяет системе Connectors обнаруживать и использовать его. Для деталей настройки см. 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. Для дополнительных примеров использования см. Использование Connectors API в динамических формах.

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

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

См. Спецификацию расширения API ConnectorClass.

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

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

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

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

#Connectors Operator API

Connectors Operator API — это набор RESTful API, предоставляемых через Connectors API, позволяющих пользователям получать информацию о Коннекторах.

Путь API: {platform_address}/clusters-rewrite/{cluster_name}/connectors-operator/{api-path}.

В настоящее время предоставляются следующие API:

• GET /connectors-operator/featureflags: возвращает информацию о feature flags системы Connectors в текущем кластере

  пример тела ответа:

  {
     "enable-connector-apis-permissions": "false",
     "enable-connectors-approval": "false",
     "enable-multi-connector": "false"
  }

  Требование по разрешениям: требуется разрешение на доступ к ConnectorClass.