译“智城云个人OpenAPI”接口规范案例

名词解释

名词	含义
applicationid	应用ID，每个开发者的唯一标识，可以在企业管理平台用户中心中查看，一个企业只有一个应用标识
applicationkey	应用密钥，每个开发者的密钥，做请求签名时必须加上的参数
openid	用户开放ID，智城云平台内部用户的唯一标识，区分每一个用户
openkey	用户开放密钥，用户鉴权后返回的随机字符串，72小时内有效，开发者需要定期更新该密钥
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数
sign	请求签名，每次请求需要带上一个签名，验证请求是否有效，签名方式可以参考【接口加密】
content-type	请求中的媒体类型信息，智城云OpenAPI中如无特殊说明，输入和输出均是application/json，对于文件上传是multipart/form-data，对于文件下载是application/octet-stream
did/deviceId	设备ID，设备唯一标识
uid/openid	用户ID，用户唯一标识

接口规范:

个人开放参数

OpenID
用户的唯一标识，智城云系统内部用户唯一标识，32位随机字符串
OpenKey
每次用户登录后会返回的有效密钥，每次会话中有效，有效期72小时，超过有效期需要重新进行鉴权。
ApplicationId
开发者的应用ID，不同的应用ID有独立的用户系统，比如相同的手机号可以在不同的应用下分别注册，应用ID可以在开发者个人中心中找到
ApplicationKey
应用Key，平台会分配给每一个应用一个单独的Key，平台会根据应用ID来判断请求是否是正确的,应用Key可以在开发者个人中心中找到

命名规范

OpenAPI采用标准的Restful规范定义接口
HTTP请求的几大关键要素：

• 请求协议
  包括安全的和非安全的协议，安全的一般为：HTTPS，非安全的为：HTTP
• 请求主机域名
  请求的域名，决定请求哪种环境，例如：api.machtalk.net,test.api.machtalk.net
• 请求地址
  请求的相对路径，类似 /v1/user,请求地址一般为名词
• 请求头信息
  头信息包括标准的头信息，如：Accept-Language，Keep-Alive等，智城云的标准开放参数也放在头信息中，如openid，openkey，applicationid，applicationkey，开放参数统一使用小写。注意Content-Type头信息对于文本型的请求统一使用application/json
• 请求方式
  请求方式包括四种：GET，POST，PUT，DELETE；标识请求的操作类型

请求方式	含义
GET	获取资源
POST	增加资源
PUT	修改资源
DELETE	删除资源

OpenAPI命名规范

• 使用有含义的英文单词
• API中包含版本号
• 使用请求方式决定操作类型，而不是将操作类型放在API地址上
• 同一模块尽量使用相同的层级，比如用户模块使用/v1/user/XX/YY,保证可读性
• API的参数会进行业务校验

接口的输入和输出

OpenAPI的输入与输出都是JSON，提交的参数以流的形式传参给服务器，服务器会把每个请求都理解为JSON字符串
智城云OpenAPI采用标准的Restful接口风格，标准的文本类接口的content-type使用application/json，输入和输出均使用标准的JSON格式，对于文件上传的接口的content-type使用multipart/form-data，对于文件下载的接口的content-type使用application/octet-stream
设备输入的参数长度不能超过2K

接口安全规范

接口请求，必须保证每次请求的安全合法，智城云OpenAPI使用SHA1对请求信息进行运算得到一个摘要进行请求的签名

智城云OpenAPI分为两类API：需要用户鉴权的和不需要用户鉴权的

• 不需要用户鉴权的：例如用户信息重复性检查，发送验证码，获取验证码凭证等，具体的可以看参数说明，不需要用户鉴权的加密方法为：SHA1(HTTPMethod+RequestURI+params+applicationkey)

• 需要用户鉴权的：例如查看用户信息，修改密码等，具体的可以看参数说明，需要用户鉴权的加密方法为：SHA1(HTTPMethod+RequestURI+params+ts+openkey+applicationkey)

接口限制

平台的接口调用并不是无限制的。为了防止开发者号的程序错误而引发服务器负载异常，默认情况下，每个应用调用接口都不能超过一定限制，当即将超过一定限制时，调用对应接口会收到错误码，同时会发送告警邮件给企业负责人和平台运维人员，基本的访问限制规则为每小时默认允许每小时调用接口4000次，超过阈值则抛错，1小时后恢复接口调用。

对于接口请求的IP如果超过一定限制也会放入请求黑名单，同时提供告警
平台会统计接口响应速度报表，提供接口服务质量依据

 

接口调用原理说明

OpenAPI调用原理说明

请求URL说明

http://[域名]/[api_name]？[k]=[v]
域名说明
正式域名使用：api.zcyun.cn
测试域名使用：test.api.zcyun.cn
api_name的说明：
[api_name]：见API列表中的接口。例如接口名称为：v1/user
请求URL的示例
http://api.zcyun.cn/v1/user

请求流程：

获取鉴权信息->确定要使用的接口名称->加密请求信息执行请求

当第一次获取了鉴权信息后可以保留在本地执行后续的请求，不必每次都获取鉴权信息

获取鉴权信息

鉴权信息接口为:/v1/user/auth
请求类型为POST，需要传入

{
    "username":"用户名/电话号码/邮箱地址",
    "password":"密码"//MD5加密后密码
}

请求的Header至少包括：

applicationid:XXXXXXXXXXXXXXXXXXXX
sign：XXXXXXXXXXXXXXXXXXXX

sign的算法为(不需要个人鉴权)：
SHA1(username+password+applicationkey)

请求的返回为：

{
    "openid":"XXXXXXXXXXXXXXXXXXXX",
    "openkey":"XXXXXXXXXXXXXXXXXXXX",
    "expiredAt":XXXXXXXXXXXXXXXXXXXX
}

本地需要重点保存openkey的值，不同语言保存的方式不同，可以根据自己的环境决定。
以后每个接口请求均需要使用这三个参数：

applicationid:XXXXXXXXXXXXXXXXXXXX
sign:XXXXXXXXXXXXXXXXXXX
openid:XXXXXXXXXXXXXXXXXXXX

确定要使用的接口名称

参考接口文档，确定自己要使用的接口名称和接口要求的最少参数，基本的接口说明至少包括如下内容：

**URL**：接口名称
**Header**：接口调用需要传输的头信息
**请求内容**：JSON格式的字符串，有些接口不会传输参数，一般GET类的接口不会有请求内容
**参数说明**：请求内容中JSON字段说明，包括数据类型，长度限制等
返回内容：接口响应结果，为JSON格式字符串，其中code为响应码，code为0表示请求成功，非0表示请求失败，具体错误信息参考错误码说明

加密请求信息执行请求

每次请求都需要使用openkey对一些参数进行加密，具体的加密流程如下：
构造加密源字符串
加密源字符串的构成:请求方式（GET等）+api_name(v1/user等，不包含？以及以后的参数)+请求内容（JSON参数，可以无）+时间戳（请求时间戳，1970年1月1日零点零分零秒到请求时刻的毫秒数）
加密钥
加密源字符串+openkey+applicationKey
生成签名
对完整字符串使用HMAC-SHA1加密算法，对于加密后的字符串使用Base64加密作为签名的最终值
这样header中的内容为：

applicationid:XXXXXXXXXXXXXXXXXXXX

openid:XXXXXXXXXXXXXXXXXXXX

sign：XXXXXXXXXXXXXXXXXXX

然后组织相应的请求参数，执行请求，等待获取返回内容，即可完成本次API请求

一个典型的请求API的Curl命令：

curl -X GET --header 'Accept: application/json' --header 'applicationid: f40f4f0b803343748bc4a7b1786cbd40' --hea

APP类接口案例：

获取最新版本信息

• 说明

  查询最新app版本信息,第一个参数是appId,第二个参数是操作系统名称，代表andriod或ios。

• URL：/v1/app/version/{appId}/{osName}

• 请求方式：GET

• Header参数：

• 请求内容：

  appId AppID（app的唯一标识）（参数在URL中）
  osName 操作系统名称:android，ios（参数在URL中）
  其他参数 无
  

• 返回内容

  成功时：

  返回内容

{
"code": 0,
"data": {
"md5": "46e35ef50341652b41573a81be6c87d3",
"versionCode": "26",
"force": 0,
"url": "http://demo.machtalk.net:8888/group1/M00/04/89/CgqcF1hN_HKAYJstAM63LvVYAOY817.apk?t=1489805045980",
"note": "1、增强APP稳定性\n2、优化设备控件",
"version": "2.0.5.3"
}
}

> 返回说明
| **参数名称** | **中文名称** | **类型** | **说明** |
| :--- | :--- | :--- | :--- |
| **version** | APP当前版本号 | JSON对象 | APP当前版本号 |
  | **versionCode** | APP版本识别码，Android使用 | JSON对象 | APP版本识别码，Android使用 |
    | **note** | APP的版本升级信息 | JSON对象 | APP的版本升级信息 |
      | **url** | APP的最新版本URL | JSON对象 | APP的最新版本URL |
          | **md5** | APP最新版本的MD5值 | JSON对象 | APP最新版本的MD5值 |
              | **force** | 是否强制升级 | JSON对象 | 是否强制升级 |

**失败时：**

{
"code": ERRORCODE //ERRORCODE可以去错误码目录中查找
}

最新版本下载地址

• 说明

  优先使用appName解析，找不到使用appId解析。

• URL：/v1/app/{appName|AppId}/download

• 请求方式：GET

• Header参数：

• 请求内容：

  appName或者AppId App名称或者app的唯一标识（参数在URL中）
  其他参数 无
  

• 返回内容

  成功时：

  返回内容

针对Andriod会返回App的二进制包
针对IOS会跳转到APP Store去下载

**失败时：**

{
"code": ERRORCODE //ERRORCODE可以去错误码目录中查找
}

通用下载页面

• 说明

  优先使用appName解析，找不到使用appId解析。如果url参数中添加了newFlag。例如v1/app/download/page/yunho?newFlag=1则会跳转到新版的下载页面。

• URL：/v1/app/download/page/{appName|appId}

• 请求方式：GET

• Header参数：

• 请求内容：

  appName App名称（参数在URL中）
  appId （app的唯一标识）（优先使用appName解析，找不到使用appId解析）
  其他参数 无
  

• 返回内容

  成功时：

  返回内容

针对Andriod会返回App的二进制包
针对IOS会跳转到APP Store去下载

**失败时：**

{
"code": ERRORCODE //ERRORCODE可以去错误码目录中查找
}