#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 и соответствовать существующим отраслевым соглашениям по именованию