API调用规范

一、概述

  1. API接口为Restful风格的HTTP接口。

  2. HTTP Request以及Response都采用JSON格式字符串作为消息实体。

    注意：文件上传或其他流式数据传输另作讨论。

  3. 采用HTTP协议的GET、POST、PUT、DELETE Method作为资源操作动作。操作原则为：

    • GET：进行数据获取，当url有参数时，需要URLEncode后方可传输；
    • POST：数据添加或者是复杂的数据查询，需要以Request Body作为查询参数的；
    • PUT：数据修改；
    • DELETE：数据删除；

在某些特殊的客户端或者云平台网络环境下，会禁用输出或者输入HTTP协议的Method为PUT或DELETE访问，Xlink API支持在Http Header添加请求头XR-Method:{PUT | DELETE}，以HTTP POST方式代理访问真实的Http Method为PUT或DELET的接口访问；

如真实的请求为：

 curl --location --request PUT 'https://api.xlink.cn/v2/device' \
--header 'Access-Token: Qz*********Rg==' \
--header 'Content-Type: application/json' \
--data '{
    "name":"new-name"
}'

以XR-Method代理方式问：

 curl --location --request POST 'https://api.xlink.cn/v2/device' \
--header 'Access-Token: Qz*********Rg==' \
--header 'Content-Type: application/json' \
--header 'XR-Method: PUT' \
--data '{
    "name":"new-name"
}'

注：仅POST请求支持XR-Method请求头。

  1. 术语
    • B端凭证：企业成员登录后换取的调用凭证
    • C端凭证：企业用户登录后换取的调用凭证
    • Empower凭证: 云云对接的调用凭证

二、针对对象

  1. 前端开发工程师，使用API进行前端产品开发
  2. 后端开发工程师，熟悉开发API规范
  3. 技术经理/架构师，了解API规范从而进行技术方案评估

三、使用场景

  1. 使用API进行前端产品开发
  2. 使用API进行二次开发以及接口聚合从而实现云云对接等类似场景

四、协议设计

4.1 URL

请求协议://访问域名/接口版本/API接口路径

4.2 请求协议

HTTPS 1.1
  • 推荐 HTTP 1.1
  • 注意：HTTPS暂不需要使用证书双向认证。

4.3 访问域名

api.domain.com
  • 注意：以最终定义域名为准。

4.4 接口路径

/v1/corp
  • 注意：接口路径的第一个字段统一为接口版本。
  • 完整地址示例：https://api.domain.com/v1/corp

五、请求头

5.1 请求头可选值

字段 说明 是否必须
Content-Type application/json 是
Access-Token 调用凭证，一般为用户登录后平台下发的用户Token 否，以具体接口为准
Corp-ID 企业标识，在使用平台权限调用时可用到 否
Api-Version 接口版本 否，以具体接口为准

5.2 请求头Access-Token

  • Access-Token为北向应用调用时所需要传递的请求头参数。
  • Access-Token主要有以下类型，具体类型说明如下：
序号 类型 获取方式 权限概述
1 Corp B端成员登录 企业B端用户权限，主要用于管理台访问平台数据，包括不限于创建获取设备数据等
2 User C端用户登录 企业C端用户权限，主要用于C端APP访问平台数据，包括不限于订阅设备、获取个人信息等
3 Empower 云云对接登录 云云对接权限，主要用于两个平台之间调用交换数据
4 Xlink 平台配置 平台级权限，主要用于平台内服务之间调用
…… …… …… ……

六、通用返回结果

6.1 V1版本

  • 该版本返回格式无固定格式，需要不同接口会有不同的返回值
  • 该版本错误时格式如下
{
	"error": {
		"code": 4001001,
		"msg": "参数不合法"
	}
}
字段 类型 是否必须 描述
error Object True 业务错误信息。
error.code Int True 业务错误码，业务错误码由各个接口来具体定义。
error.msg String True 错误的详细信息描述。

6.2 V2版本

  • 该版本为固定返回格式，如下
{
  "code": "业务错误码",
  "status": "http状态码",
  "msg": "错误异常信息",
  "data": {
    "返回参数Key":"返回参数值"
  }
}
字段 类型 是否必须 描述
code Long True 业务错误码，业务错误码由各个接口来具体定义。200代表成功，其他代表失败。业务错误码见下方示例以及分段说明
status Integer False 通用HTTP状态码，200表示执行成功。其他表示错误或其他返回，看附录的HTTP状态码定义。
msg String True 错误的详细信息描述。请求错误时存在；否则为”” 空字符。
data Object True 具体的接口响应数据。无实际响应数据时，该字段为空对象{}。其他数据以具体接口为准。

七、错误码定义

7.1 HTTP状态码(status)

值 描述
200 请求成功
302 重定向跳转
400 请求字段不合法
401 缺少调用凭证
403 授权不通过
404 资源不存在
405 方法不支持
502 响应超时
503 参数解析错误
504 服务器异常

八、示例

  • 由于在开发中主要以B端和C端调用为主，为此以以下两种场景为例子，具体如下:

8.1 B端认证示例

8.1.1 获取Access-Token

8.1.1.1 Request
  • URI
/v2/corp-auth
  • HOST
https://api.domain.com
  • Method
POST
  • Header
名称 值 必填
Content-Type application/json true
  • Body
{
    "account": "demo@xlink.cn",
    "password": "Test123456"
}
名称 位置 必填 类型 备注
account body true String 企业成员账号
password body true String 企业成员密码
8.1.1.2 Response
  • Body
{
	"member_id": "1207d2ad165a7001",
	"access_token": "QkIzNUM2NERCOTNGCRUU0NUVGQjFCMDhBOTA4NEZBMjlDQzI0MDlDQTBCNzAwOA==",
	"refresh_token": "NjY3OTZDM0E3RkE0MjNGN0MwQzUxQkYzRTJDMjZGODc2RkI3MUQzOTkyRjUxNw==",
	"role_type": 0,
	"expire_in": 7200,
	"corp_id": "1007d2ad165a7000"
}
名称 必填 类型 描述
corp_id true String 企业标识
member_id true String 企业成员标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证过期时长

8.1.2 发起调用

8.1.2.1 Request
  • URI
/v2/api-gateway/demo
  • HOST
https://api.domain.com
  • Method
POST
  • Header
名称 值 必填
Content-Type application/json true
Access-Token 调用凭证 true, 8.1.1获取到的B端access_token
  • Body
{
    "name": "xlink",
    "age": 19
}
名称 位置 必填 类型 备注
name body true String 名称
age body true Int 年龄
8.1.2.2 Response
  • Body
{
	"code": 200,
	"status": 200,
	"msg": "",
	"data": {
		"age": 19,
		"name": "xlink"
	}
}
字段 必填 类型 备注
code true Long HTTP状态码
status false Int 业务错误码
msg true String 业务错误信息
data true Object 业务数据
data.age true Int 年龄
data.name true String 名词

8.2 C端认证示例

8.2.1 获取Access-Token

8.2.1.1 Request
  • URI
/v2/user_auth
  • HOST
https://api.domain.com
  • Method
POST
  • Header
名称 值 必填
Content-Type application/json true
  • Body
{
    "corp_id": "1207d2ad165a7001",
    "phone": "13838383388",
    "phone_zone": "+86",
    "password": "Test123465",
    "resource": "Test",
    "email": "liqinghua@xlink.cn"
}
字段 位置 必填 类型 备注
corp_id body true String 企业标识
phone body false String 用户手机号,与用户邮箱二选一
phone_zone body true String 用户手机区号
password body true String 用户密码
resource body false String 用户登录源
email body false String 用户邮箱,与用户手机号二选一
8.2.1.2 Response
  • Body
{
	"user_id": 4452451254,
	"access_token": "QkIzNUM2NERCOTNGCRUU0NUVGQjFCMDhBOTA4NEZBMjlDQzI0MDlDQTBCNzAwOA==",
	"refresh_token": "NjY3OTZDM0E3RkE0MjNGN0MwQzUxQkYzRTJDMjZGODc2RkI3MUQzOTkyRjUxNw==",
	"expire_in": 7200
}
字段 必填 类型 备注
user_id true Int 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证过期时长

8.2.2 发起调用

8.2.2.1 Request
  • URI
/v2/api-gateway/demo
  • HOST
https://api.domain.com
  • Method
POST
  • Header
字段 值 必填
Content-Type application/json true
Access-Token 调用凭证 true, 8.2.1获取到的C端access_token
  • Body
{
    "name": "xlink",
    "age": 19
}
名称 位置 必填 类型 备注
name body true String 名称
age body true Int 年龄
8.2.2.2 Response
  • Body
{
	"code": 200,
	"status": 200,
	"msg": "",
	"data": {
		"age": 19,
		"name": "xlink"
	}
}
字段 必填 类型 备注
code true Long HTTP状态码
status false Int 业务错误码
msg true String 业务错误信息
data true Object 业务数据
data.age true Int 年龄
data.name true String 名词
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题