智能家居后端技术解决方案-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

嵌入式请求参数

App 请求参数

小程序请求参数

管理后台请求参数

协议概述

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

version 1:

version 2：

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

字节位字段说明:

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

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

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: 超时