开发者中心

Appearance

MQTT 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的接口访问；

如真实的请求为：

sh
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代理方式问：

sh
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

五、请求头 ​

5.1 请求头可选值 ​

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

5.2 请求头Access-Token ​

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

六、通用返回结果 ​

6.1 V1版本 ​

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

6.2 V2版本 ​

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

七、错误码定义 ​

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-Typeapplication/jsontrue
  • Body
json
{
    "account": "demo@xlink.cn",
    "password": "Test123456"
}
名称位置必填类型备注
accountbodytrueString企业成员账号
passwordbodytrueString企业成员密码
8.1.1.2 Response ​
  • Body
json
{
	"member_id": "1207d2ad165a7001",
	"access_token": "QkIzNUM2NERCOTNGCRUU0NUVGQjFCMDhBOTA4NEZBMjlDQzI0MDlDQTBCNzAwOA==",
	"refresh_token": "NjY3OTZDM0E3RkE0MjNGN0MwQzUxQkYzRTJDMjZGODc2RkI3MUQzOTkyRjUxNw==",
	"role_type": 0,
	"expire_in": 7200,
	"corp_id": "1007d2ad165a7000"
}
名称必填类型描述
corp_idtrueString企业标识
member_idtrueString企业成员标识
access_tokentrueString调用凭证
refresh_tokentrueString刷新凭证
expire_intrueInt调用凭证过期时长

8.1.2 发起调用 ​

8.1.2.1 Request ​
  • URI
/v2/api-gateway/demo
  • HOST
https://api.domain.com
  • Method
POST
  • Header
名称值必填
Content-Typeapplication/jsontrue
Access-Token调用凭证true, 8.1.1获取到的B端access_token
  • Body
json
{
    "name": "xlink",
    "age": 19
}
名称位置必填类型备注
namebodytrueString名称
agebodytrueInt年龄
8.1.2.2 Response ​
  • Body
json
{
	"code": 200,
	"status": 200,
	"msg": "",
	"data": {
		"age": 19,
		"name": "xlink"
	}
}
字段必填类型备注
codetrueLongHTTP状态码
statusfalseInt业务错误码
msgtrueString业务错误信息
datatrueObject业务数据
data.agetrueInt年龄
data.nametrueString名词

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-Typeapplication/jsontrue
  • Body
json
{
    "corp_id": "1207d2ad165a7001",
    "phone": "13838383388",
    "phone_zone": "+86",
    "password": "Test123465",
    "resource": "Test",
    "email": "liqinghua@xlink.cn"
}
字段位置必填类型备注
corp_idbodytrueString企业标识
phonebodyfalseString用户手机号,与用户邮箱二选一
phone_zonebodytrueString用户手机区号
passwordbodytrueString用户密码
resourcebodyfalseString用户登录源
emailbodyfalseString用户邮箱,与用户手机号二选一
8.2.1.2 Response ​
  • Body
json
{
	"user_id": 4452451254,
	"access_token": "QkIzNUM2NERCOTNGCRUU0NUVGQjFCMDhBOTA4NEZBMjlDQzI0MDlDQTBCNzAwOA==",
	"refresh_token": "NjY3OTZDM0E3RkE0MjNGN0MwQzUxQkYzRTJDMjZGODc2RkI3MUQzOTkyRjUxNw==",
	"expire_in": 7200
}
字段必填类型备注
user_idtrueInt用户标识
access_tokentrueString调用凭证
refresh_tokentrueString刷新凭证
expire_intrueInt调用凭证过期时长

8.2.2 发起调用 ​

8.2.2.1 Request ​
  • URI
/v2/api-gateway/demo
  • HOST
https://api.domain.com
  • Method
POST
  • Header
字段值必填
Content-Typeapplication/jsontrue
Access-Token调用凭证true, 8.2.1获取到的C端access_token
  • Body
json
{
    "name": "xlink",
    "age": 19
}
名称位置必填类型备注
namebodytrueString名称
agebodytrueInt年龄
8.2.2.2 Response ​
  • Body
json
{
	"code": 200,
	"status": 200,
	"msg": "",
	"data": {
		"age": 19,
		"name": "xlink"
	}
}
字段必填类型备注
codetrueLongHTTP状态码
statusfalseInt业务错误码
msgtrueString业务错误信息
datatrueObject业务数据
data.agetrueInt年龄
data.nametrueString名词