目录 (Table of Contents)

• API 公共部分说明
  • 基本概念
  • 公共请求头说明
    • POST和PUT请求
    • Authorization加签规则
  • 公共返回头说明
  • 返回码

API 公共部分说明

基本概念

• appId/appKey : 主要是用于对用户调用行为进行鉴权和认证，相当于开放平台接口调用的用户名及密码。
• 当接口定义中出现时间时，如果没有特殊的说明，单位为unix毫秒时，表示一个时间点。
• 流量单位默认为 Byte，但是也有接口会用到MB和KB，具体的接口会对应的在参数中加以说明。
• 金钱单位默认为 千分之一分，相当于0.00001元人民币。
• 数据格式的编码统一为UTF-8。

公共请求头说明

头信息中应包含下列信息。

POST和PUT请求

POST和PUT请求体为参数类型时，需要使用json格式的参数传输数据。

Authorization加签规则

对 appkey 、HTTP请求方法（全大写）、资源路径 、查询语句（POST的时候不存在）、请求体（GET的时候不存在）依次进行字符串拼接。然后再对得到的字符串进行md5加密就得到我们的签名。

参数说明 请特别注意中文传输的问题。在qureyString 和 requestBody中都要进行不同的中文转码然后进行加签计算，这样可以保证我们双方的加签验签有效完成。请在发送时。尽量在日志中打印自己的签名计算时的数值（除了自己的秘钥外）。便于出现签名问题时进行查找问题。

请求的URL为 http://domainName:port/resourcesPath?queryString。

httpMethod ：表示HTTP 请求的Method，主要有PUT，GET，POST，HEAD，DELETE等。

resourcesPath : 表示网络服务器上资源的路径,这里需要加上最前面的那个'/'。

queryString : 提供给网络服务器的额外参数，获取到url上的参数，参数顺序必须与请求url中的参数顺序一致。 如果传入的是中文，请编码为URL规则（例如：'李四'的queryString为'%e6%9d%8e%e5%9b%9b'）这是因为url不能传播中文字符。导致服务器收到的数据就是验签的时候就是使用的传入的数据

requestBody : 表示http请求的请求的请求体。当请求体中出现中文时。请对中文使用uncode编码，例如： '你好' 换成 '\u4f60\u597d'

伪代码

当HTTP请求方法为GET或者DELELE请求时，参数只存在于queryString， 当HTTP请求方法为POST或者PUT的时候，接口定义参数只存在于requestBody。

• 1、请求为GET或者DELETE请求时

Authorization = "Basic " + Signature

Signature = MD5(
                appKey + 
                httpMethod + 
                resourcesPath +
                queryString +
                )

• 2、请求为POST或者PUT请求时

Authorization = "Basic " + Signature

Signature = MD5(
                appKey + 
                httpMethod + 
                resourcesPath +
                requestBody +
                )

当验证无法通过的时候，会返回403 并返回无法通过的原因。

Java代码示例

请求为

GET /sim/1068888800000/info HTTP/1.1
Host: api.miot.10046.mi.com
Date: Thu, 15 May 2014 11:18:32 GMT
H-XM-AppId: 100016//开放平台分配给接入方的appId
H-XM-V: 2.0    //接口版本号
Authorization: Basic kdsfjksdfksdfjkdssfddk      //填写计算后的结果
Content-Type: application/json;charset=UTF-8

计算为

String Signature = new String(new Md5Hash(
                    appKey  +
                    "GET" + 
                    "/sim/1068888800000/info" + 
                    "" +  // 没有parameters url附加参数就留空
                    "" // 没有requestBody就留空
                ).toString())
String Authorization = "Basic "  + Signature;

计算出的签名和请求头的 Authorization: Basic kdsfjksdfksdfjkdssfddk 一致就表示验签成功。

加签验证的好处

• 1、认证字符串使用指定用户的appId/appKey对HTTP请求进行签名，可以起到验证用户身份的作用。

• 2、用户基于HTTP请求的指定内容生成认证字符串，如果在传输过程中遭到非法篡改，将导致系统生成的认证字符串与用户生成的认证字符串不匹配，最终导致认证失败。

• 3、保护用户的appKey信息,不直接使用appKey进行验证，防止盗用。
• 4、使用最简单方式的md5加密保证了大多数的语言可以使用。

公共返回头说明

头信息描述

当返回信息为错误，但调用方无法定位问题时，可以提供对应的H-XM-Request-Id 服务端帮忙查询系统日志定位问题。

返回码

本API 遵循 RESTFUL 方式的响应，通过HTTP Status Code来说明API请求状态。 启用返回码的目的是为了更好的定位调用过程中遇到的各种问题，并且对问题进行统一的管理和检测。