智能家居后端技术解决方案-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 |
字节位字段说明:
- version: 从1开始递增. version 2 开始引入数据包协议层加密，data为加密数据，加密逻辑由version决定
version2 加密方式：AES-256-CBC+PKCS7UnPadding，key从服务器获取
- action: 表示应用场景类型. 数字类型从1递增, 可选值如下:
- 1: 表示push, 用于推送和数据上报场景, 不需要响应
- 2: 表示call, 用于查询和操作资源, 需要对方响应结果
- 3: 表示reply, 用于响应结果, 如果content-length=0表示接收到消息, 但不需要返回结果
- 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: 超时
