API接口规范
规范
名称 | 值 |
---|---|
请求基础地址 | xxx.com/api/v1/ |
请求方式 | GET/POST/PUT/DELETE |
请求body提交方式 | 以x-www-form-urlencoded提交 |
响应文档格式 | application/json |
响应http_code | 200 |
系统query参数
名称 | 类型 | 说明 |
---|---|---|
random | string | 随机字符串,长度8-20 |
timestamp | int | 当前请求unix时间戳,长度10 |
sign | string | 数据签名,长度32 |
random参数说明
random为8-20位随机字符串。
timestamp参数说明
timestamp时间为请求当前时间,将与北京时间相比较,允许60分钟误差,超过60分钟则判定请求无效。若实现语言为php5,请将timestamp改为atimestamp
。
sign参数说明
sign算法,请求中的query参数+body参数(包括app_sign)+random+timestamp,ascii排序
后使用特殊字符 &
拼接(key1=val1&key2=val2..)后再MD5加密。
优先进行app_sign签名,再进行sign签名,sign签名时app_secret不参与签名。
业务参数
API调用除了必须包含公共参数外,如果API本身有业务级的参数也必须传入,每个API的业务级参数请考API文档说明。
请求方式说明
- PUT请求请以x-www-form-urlencoded方式提交
- 若PUT请求需提交文件,请以POST方式+参数中添加_method=PUT的形式提交,_method参与签名
请求响应公共参数
名称 | 类型 | 说明 |
---|---|---|
msg | string | 响应消息 |
code | int | 响应码 |
data | mixed | 响应数据 |
响应demo
// 成功
{
"code": 200,
"msg": "ok",
"data": {
"time": "2016-08-02 12:07:09"
}
}
// 失败
{
"code": 1001,
"msg": "random长度不对",
"data":null
}
响应code码范围附录
范围 | 说明 |
---|---|
200-599 | 同HTTP状态码 |
1000-9999 | 公共错误码 |
10000-99999 | 业务错误码 |
详细列表参考这里