##命令规范
所有参数以及返回参数,均按照under_stores方式
##UrlPrefix
/v1/
prefix采用版本号,类似/v1/来标识相关api
现在的版本为v1
##Parameter
必需参数部分,采用header+parameter相结合的方式
- header部分
-
User-Agent
每个请求在头部user-agent均需带有下列参数
andriod:
kika/90 (1a14a0a6d44db2a591f166aa2dc95a6b/78472ddd7528bcacc15725a16aeec190) Country/cn Language/zh System/android Version/6.0 Screen/xhdpi
ios:
coolkeyboard/12 (1a14a0a6d44db2a591f166aa2dc95a6b/4a5ae1b93f21afaf199a6b3140e05097) Country/cn Language/zh System/iSO Version/9.0 Screen/iphone6
-
含义为:应用名/app_version (duid/app_key) 国家 语言 系统 系统版本 分辨率
大致为136字节,
-
parameter部分
-
sign
接口的签名。
该值由app_key,app_version,duid三个参数md5计算得到,字符串的形式为
app_key4a5ae1b93f21afaf199a6b3140e05097app_version90duid1a14a0a6d44db2a591f166aa2dc95a6b
按照app_key,app_version,duid的顺序,对上述字符串进行utf-8编码的字节序列进行md5编码。
示例:接口签名工具类
-
这里对一些非必需参数进行说明:
- pre_cursor, next_cursor int
指明当前游标,即from, to
或者
- cursor
默认为当前游标,默认取20,作为游标长度
接口部分,通过sign参数,客户端传入相关的md5计算值,后端进行验证。
为了方便调试线上,增加debug模式,在此模式,不会验证相关安全性部分的内容,相关header部分的参数也不会验证,同时,在输出部分,增加例如接口耗时等相关信息
-
is_debug=true true,false
指明是否为调试模式,true为调试,false为非,默认非调试模式
##请求协议
除用户信息上抛接口(包含gcm上抛)采用POST协议,其余统一为Get协议
##接口分类
###Theme
###Ads
/resources/
- stickerList
/stickers/list
针对某个app的sticker列表
##Response
状态码 | 意义 |
---|---|
200 | 请求成功 |
422 | 请求参数错误 |
403 | 签名非法,不允许访问 |
404 | 请求资源不存在 |
500 | 服务器内部错误 |
均为json数据。示例:
{
"errorCode":0,
"errorMsg":"ok",
"data": {
"timeused":120, //debug模式生效
"name":"test",
"priority":1,
"float":1.0,
"list":[
{
"pic":"https://s3.amazonaws.com/keyboard_pic/2015082510050981yali.jpg"
}
],
"pre_cursor" : 3,
"next_cursor" : 4,
"total_count" : 19
}
}
- int
default: 0
- string
default: ""
- float
default: 0.0
- list
default: []
其中,timeuse字段,标明该接口的后端耗时,且仅在调试模式下生效
errorCode | errorMsg | statusCode | 信息 |
---|---|---|---|
0 | ok | 200 | 正常请求成功 |
40001 | no result | 200 | 没有数据 |
30001 | invalid interface sign | 403 | 接口签名错误 |
30002 | invalid request method | 404 | 请求的method不存在 |
30003 | basic parameter miss, xxx | 422 | 基本的请求参数验证失败,即duid,appKey,appVer存在空值 |
30004 | request parameter miss, xxx | 422 | 接口所需的其他参数缺失 |
30005 | invalid request paramter, xxx | 422 | 参数验证非法 |
30006 | service fatal error | 500 | 服务器内部错误 |
30007 | redis network fail | 500 | 连接redis服务器失败 |
30008 | redis no data | 500 | redis请求数据为空 |
其中,300xx错误主要是服务器验证以及服务连接相关错误,400xx主要是针对业务部分错误,如没有数据等
主要针对返回带有list的情况
非必需参数中:
/sticker/list
改为/stickers
更好一些吧。