#ConnectorClass API Extension

#Overview

Расширение API ConnectorClass по сути сводится к созданию Restful API сервера. При расширении возможностей API для ConnectorClass необходимо включить две части информации:

1. Указать информацию об адресе API в поле spec.api ConnectorClass. Это позволяет системе знать текущий адрес API для ConnectorClass. См. раздел «API Address Specification».
2. Реализовать Restful API сервер для ConnectorClass. См. раздел «API Definition Specification».

#API Address Specification

Информация об адресе API должна быть указана в поле spec.api ConnectorClass.

Нет ограничений по тому, должен ли сервис API ConnectorClass находиться внутри текущего кластера. Главное, чтобы система Connectors могла достучаться до адреса сервиса.

Конфигурация полей может ссылаться на описание connectorclass api в connectorclass.

#API Definition Specification

#API Address

Когда система Connectors получает запрос от клиента, она перенаправляет запрос на адрес API ConnectorClass, к которому принадлежит Connector.
Адрес API имеет формат {connectorclass.status.api.address.url}/{resource-name}

#Authentication Information

При переадресации API-запросов система Connectors передаёт информацию для аутентификации сервису API ConnectorClass через Http Header.
Информация для аутентификации включает:

• Tool Address Information: передаётся через Http Header X-Plugin-Meta.
• Authentication Type: передаётся через Http Header X-Plugin-Auth.
• Authentication Data: передаётся через Http Header X-Plugin-Secret.

X-Plugin-Meta

Значение — строка, закодированная в Base64, содержащая {"baseURL":"Адрес инструмента Connector"}. Например:

{"baseURL":"http://github.com"} кодируется в eyJiYXNlVVJMIjoiaHR0cDovL2dpdGh1Yi5jb20ifQ==

При декодировании значение Base64 из заголовка даёт JSON-строку {"baseURL":""}, где значение baseURL — это адрес доступа к инструменту.

X-Plugin-Auth

Значение — строка, закодированная в Base64, представляющая K8S Secret Type.

Например, kubernetes.io/basic-auth кодируется в a3ViZXJuZXRlcy5pby9iYXNpYy1hdXRo

При декодировании значение Base64 из заголовка позволяет получить Secret Type.

X-Plugin-Secret

Значение — строка, закодированная в Base64, представляющая JSON-строку с данными K8S Secret Data.

Например, {"username":"YWRtaW4=","password":"c2VjcmV0"} кодируется в eyJ1c2VybmFtZSI6IllXUnRhVzQ9IiwicGFzc3dvcmQiOiJjMlZqY21WMCJ9

При декодировании значение Base64 из заголовка даёт JSON-строку {"username":"YWRtaW4=","password":"c2VjcmV0"}. Для доступа к значению ключа необходимо снова выполнить base64-декодирование, чтобы получить исходное значение.

Пример запроса

GET /api/gitrefs?repositoryUrl=https%3A%2F%2Fgithub.com%2FAlaudaDevops%2Fconnectors.git HTTP/1.1
Host: 192.168.162.100:8080
X-Plugin-Meta: eyJiYXNlVVJMIjoiaHR0cHM6Ly9naXRodWIuY29tIn0=
X-Plugin-Auth: a3ViZXJuZXRlcy5pby9iYXNpYy1hdXRo
X-Plugin-Secret: eyJwYXNzd29yZCI6ImNHRnpjekV5TXc9PSIsInVzZXJuYW1lIjoiWVdSdGFXND0ifQ==

#Pagination Information

Указывается через параметры Query:

#Response

При возврате списка структура должна быть следующей:

{
    "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

#Resource Naming

Разработчики могут определять самостоятельно. Рекомендуется:

• Имя в нижнем регистре во множественном числе
• Имя должно быть уникальным в пространстве имён текущего ConnectorClass и соответствовать существующим отраслевым соглашениям по именованию.