智能家居后端技术解决方案-API设计

一、采用HTTP和MQTT协议进行数据交互和通信

API 请求签名

对于每一次发送给后端服务器的HTTP和MQTT协议请求，我们会根据访问中的签名信息验证访问请求者身份。具体由使用authToken_和authSecret_对称加密验证实现。其中authToken_是访问者身份，authSecret_是加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密谨防泄露。 

签名

签名采用HmacSHA1算法 + Base64，编码采用UTF-8。签名之前需要将body内容与上一步中得出的待签名字符串拼接在一起, 如果没有body则不用拼接. 

公共请求参数

API 接口中使用了公共参数, 携带在URI的query中. HTTP是url, MQTT是payload header uri

嵌入式请求参数

名称	类型	是否必填	说明
firmwareVer_	string	是	固件版本号
softwareVer_	string	是	软件版本号
deviceModel_	string	是	设备产品型号
ts_	int64	是	当前Unix时间戳

App 请求参数

名称	类型	是否必填	说明
platform_	string	是	系统平台, 可选: android, ios
deviceVer_	string	是	系统版本号
deviceModel_	string	否	手机厂商, 如: apple, vivo, xiaomi, oppo等
appVer_	string	是	App 版本号, versionName
appChannel_	string	否	App 下载安装渠道, 如: appstore, xiaomi
net_	string	否	网络类型, 如: wifi, 3g, 4g, 5g
ts_	int64	是	当前Unix时间戳
authType_	string	否	登录成功, 都必须携带该参数. 固定值:xxx
authToken_	string	否	登录成功后返回的身份令牌, 之后的请求都必须携带该参数.
sign_	string	否	登录成功, 获得auth_secret_后, 之后的请求都必须携带该参数

小程序请求参数

名称	类型	是否必填	说明
platform_	string	是	系统平台, 可选: wechat
ts_	int64	是	当前Unix时间戳
authType_	string	否	登录成功, 都必须携带该参数. 固定值: wx_lite
authToken_	string	否	登录成功后返回的身份令牌, 之后的请求都必须携带该参数.
sign_	string	否	登录成功, 获得auth_secret_后, 之后的请求都必须携带该参数

管理后台请求参数

名称	类型	是否必填	说明
platform_	string	是	系统平台, 可选: pc, pad
ts_	int64	是	当前Unix时间戳
authType_	string	否	登录成功, 都必须携带该参数. 固定值: admin
authToken_	string	否	登录成功后返回的身份令牌, 之后的请求都必须携带该参数.
sign_	string	否	登录成功, 获得auth_secret_后, 之后的请求都必须携带该参数

协议概述

通讯数据协议是应用协议(mqtt,bluetooth,跨平台调用等)之上的业务通讯数据规范, 一套规范适用于各平台的数据调用交互. 数据格式为byte array, 协议分为 header 和 payload. 其中, header 表达数据交互动作等基础信息, payload与业务关联性更近, 包含 payload header 和payload body. 数据字节位如下:

version 1:

	header			payload
字节位
Bit 1
Bit 2	Bit 3 ~ Bit 6
payload header	payload body
说明
version	action	payload header length
bytes	bytes

version 2：

| | header | data | | | :---: | :---: | :---: | --- | | 字节位 | Bit 1 | Bit 2~ | | | 说明 | version | data | |

data
	header		payload
字节位	Bit 1	Bit 2 ~ Bit 5	payload header	payload body
说明	action	payload header length	bytes	bytes

字节位字段说明:

1. version: 从1开始递增. version 2 开始引入数据包协议层加密，data为加密数据，加密逻辑由version决定

version2 加密方式：AES-256-CBC+PKCS7UnPadding，key从服务器获取

1. action: 表示应用场景类型. 数字类型从1递增, 可选值如下:
   1. 1: 表示push, 用于推送和数据上报场景, 不需要响应
   2. 2: 表示call, 用于查询和操作资源, 需要对方响应结果
   3. 3: 表示reply, 用于响应结果, 如果content-length=0表示接收到消息, 但不需要返回结果
2. payload header: 可扩展的payload协议头, key-value 对, 每对之间使用\n分割.  key和value之间使用英文冒号分割. 如:

content-type:json\ncontent-lenght:12

payload body: 协议无关的业务数据

payload 基础字段说明

payload header

以下是通用的字段, 可根据实际业务需要再进行扩展

字段名	HTTP Header Key	type	action	option	说明
uri	无	string	all	必需	标准资源路径, 可支持 query 参数
identifier	x-indentifer	string	all	必需	该次请求的id标识, 用于关联响应
length	length	int32	all	必需	body 数据长度; 默认0
status	status	int	reply	必需	响应状态码
info	x-info	string	reply	必需	响应状态信息, 可用于调试错误信息显示
encrypted	x-encrypted	string	all	可选	标识body数据包加密方式; 可选[aes]
accept-encrypted	x-accept-encrypted	string	call	可选	标识接收的body数据包加密方式; 可选[aes], 不填写则根据encrypted决定

payload body

call和push类型的body没有公共字段, 直接发送业务数据. reply 类型需要遵从以下字段格式(以json为例):

{ "data": {} // 业务数据 "error": { // 业务错误信息, 当status=299时才有 "code": 0, // 业务错误码 "message": "" // 错误信息文案, 展示给用户 } }

status 可选值如下:

• 200: ok
• 299: 业务错误
• 400: 参数错误
• 401: 未授权的请求
• 404: 无效的uri
• 500: 对方服务内部错误
• 502: 网关错误
• 504: 超时