ConnectorClass API 扩展

Overview

扩展 ConnectorClass API 本质上是创建一个 Restful API Server。在扩展 ConnectorClass 的 API 能力时，需要包含两部分信息：

在 ConnectorClass 的 spec.api 字段中指定 API 地址信息，使系统能够知道该 ConnectorClass 当前的 API 地址。请参见“API 地址规范”。
实现 ConnectorClass 的 Restful API Server。参见“API 定义规范”。

API 地址规范

API 地址信息必须在 ConnectorClass 的 spec.api 字段中指定。

ConnectorClass API 服务是否部署在当前集群内没有限制，只要 Connectors 系统能够访问该服务地址即可。

字段配置可参考 connectorclass 中 connectorclass api 的描述。

API 定义规范

API 地址

当 Connectors 系统接收到客户端请求时，会将请求转发到该 Connector 所属 ConnectorClass 的 API 地址。
API 地址格式为 {connectorclass.status.api.address.url}/{resource-name}。

认证信息

转发 API 请求时，Connectors 系统会通过 Http Header 向 ConnectorClass API 服务传递认证信息。
认证信息包括：

工具地址信息：通过 Http Header X-Plugin-Meta 传递。
认证类型：通过 Http Header X-Plugin-Auth 传递。
认证数据：通过 Http Header X-Plugin-Secret 传递。

X-Plugin-Meta

该值是一个 Base64 编码的字符串，内容为 {"baseURL":"Connector Tool Address"}，例如：

{"baseURL":"http://github.com"} 编码后为 eyJiYXNlVVJMIjoiaHR0cDovL2dpdGh1Yi5jb20ifQ==

解码时，从 Header 中获取 Base64 值，解码后得到 JSON 字符串 {"baseURL":""}，其中 baseURL 的值即为工具的访问地址。

X-Plugin-Auth

该值是一个 Base64 编码的 K8S Secret Type 字符串。

例如，kubernetes.io/basic-auth 编码后为 a3ViZXJuZXRlcy5pby9iYXNpYy1hdXRo

解码时，从 Header 中获取 Base64 值，解码后得到 Secret Type。

X-Plugin-Secret

该值是一个 Base64 编码的 JSON 字符串，表示 K8S Secret Data。

例如，{"username":"YWRtaW4=","password":"c2VjcmV0"} 编码后为 eyJ1c2VybmFtZSI6IllXUnRhVzQ9IiwicGFzc3dvcmQiOiJjMlZqY21WMCJ9

解码时，从 Header 中获取 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==

分页信息

通过 Query 参数指示：

参数名称	类型	必填	描述
page	int	否	页码
itemsPerPage	int	否	每页条目数

响应

返回列表时，结构应如下：

字段名	类型	必填	描述
listMeta	ListMeta	是	列表元数据
listMeta.totalItems	int	是	请求资源总数，客户端用于分页分析
items	[]	是	列表数据项，其结构由 ConnectorClass API 决定

{
    "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 保持一致。

资源命名

开发者可自行定义。建议包括：

使用小写复数形式命名
名称应在当前 ConnectorClass 的命名空间内唯一，并符合现有行业命名规范

#ConnectorClass API 扩展

#目录

#Overview

#API 地址规范

#API 定义规范

#API 地址

#认证信息

#分页信息

#响应

#资源命名