# 通讯协议
KIC采用HTTP REST API形式提供接口服务，并使用JWT(RFC 7519) (opens new window)进行认证鉴权，详见认证鉴权。
支持 HTTP/2.0
# 请求地址 URI
API请求URI由如下部分组成：
{URI-scheme}://{Endpoint}/{API-path}?{Query-string}
| 参数 | 描述 |
|---|---|
| Scheme | 表示用于传输请求的协议，当前所有API均采用HTTPS协议。 |
| Endpoint | API访问节点，可以在控制台中的应用详情获取，参见 访问节点 Endpoints |
| API-path | API访问路径。从具体API的URI模块获取 |
| Query-string | 查询参数，是可选部分，并不是每个API都有查询参数。 查询参数前面需要带一个 ?，形式为参数名=参数取值 |
例如获取设备信息接口的URI为：
https://api-cn-main.kfbcloud.com/api/client/info?uuid=xxxxxxxxx
# 访问节点 Endpoints
| 区域 | Endpoint |
|---|---|
| 中国大陆主节点 | api-cn-main.kfbcloud.com |
# 请求方法 Method
HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。
| 方法 | 说明 |
|---|---|
| GET | 请求服务器返回指定资源。 |
| PUT | 请求服务器更新指定资源。 |
| POST | 请求服务器新增资源或执行特殊操作。 |
| DELETE | 请求服务器删除指定资源，如删除对象等。 |
| HEAD | 请求服务器资源头部。 |
| PATCH | 请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会去创建一个新的资源。 |
提示
为了简化协议，KIC大部分的请求方法为GET、POST
# 请求消息头 Header
附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头Content-Type，请求鉴权信息等。
| 名称 | 描述 | 必选 |
|---|---|---|
| Host | 请求的服务器信息，从服务API的URL中获取。值为hostname[:port]。 端口缺省时使用默认的端口，https的默认端口为443。 | 是 |
| Content-Type | 消息体的类型（格式）。 当前默认为application/json，有其他取值时会在具体接口中专门说明。 | 是 |
| Content-Length | 请求body长度，单位为Byte。 | 否 |
| Authorization | 认证鉴权信息。除了获取授权接口，其他接口都必须携带此请求头。 该值为调用获取授权接口获取的token值。 | 否 |
# 请求消息体 Body
该部分可选。请求消息体通常以结构化格式（ 默认为JSON）发出，与请求消息头中Content-Type对应，传递除请求消息头之外的内容。若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。
每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。
到这里为止这个请求需要的内容就具备齐全了，您可以使用curl (opens new window)、Postman (opens new window)或直接编写代码等方式发送请求调用API。
# 响应状态码 StatusCode
请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。
状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见状态码。
| 正常状态码 | 描述 |
|---|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted |
| 204 | No Content |
提示
为了简化协议，KIC大部分的正常状态码为200
| 错误状态码 | 描述 |
|---|---|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 409 | Conflict |
| 413 | Request Entity Too Large |
| 415 | Unsupported Media Type |
| 500 | Internal Server Error |
| 501 | Not Implemented |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
| 504 | Gateway timeout |
# 响应消息头 Header
对应请求消息头，响应同样也有消息头，如Content-type。
# 响应消息体 Body
该部分可选。响应消息体通常以结构化格式（JSON）返回，与响应消息头中Content-Type对应，传递除响应消息头之外的内容。
例如成功调用获取授权接口，返回如下消息体。
{
"code": 0,
"msg": "ok",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoicWFVN1ZmMzZaemlpIiwiZXhwIjoxNjI3OTExNDIzLCJpc3MiOiJLSUMifQ.eb6V-Ir-qvQs2v0kNOIFZwUn_qgmEG1vyKS29LwLXog",
"expires_at": 1627911423
}
}
2
3
4
5
6
7
8
当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。
{
"code": 20004,
"msg": "授权失败",
"data": null
}
2
3
4
5
其中，code表示错误码，msg表示错误描述信息。