Kika Api RESTful API Design

KARAD.md

#Kika Api RESTful API Design

##命令规范

所有参数以及返回参数，均按照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模式

为了方便调试线上，增加debug模式，在此模式，不会验证相关安全性部分的内容，相关header部分的参数也不会验证，同时，在输出部分，增加例如接口耗时等相关信息

• is_debug=true true,false

  指明是否为调试模式，true为调试，false为非，默认非调试模式

##请求协议

###外部接口

除用户信息上抛接口(包含gcm上抛)采用POST协议，其余统一为Get协议

###内部接口

##接口分类

###Theme

---

###Ads

---

###Basic

Dict

Json

###Resource

/resources/

Sticker

---

• stickerList

/stickers/list

针对某个app的sticker列表

###Gcm

###User

##Response

###HttpStatus

状态码	意义
200	请求成功
422	请求参数错误
403	签名非法，不允许访问
404	请求资源不存在
500	服务器内部错误

###struct

均为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

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主要是针对业务部分错误，如没有数据等

###cursor&totoal

主要针对返回带有list的情况

1. 所有参数及返回，应按照 underscore_case 而不是 camelCase，而且全为小写
2. Parameter 部分，

duid=[duid] string
appKey=[appKey] string
appVersion=[appVersion] Int 这块取客户端的整数版本

• 可否放在 Header 中？
• duid 是什么？是指 uuid 还是 udid 还是？
• 请求参数中，需要分别 string 和 int 的原因是？

非必需参数中：

这里对一些非必需参数进行说明：

currPage=[currPage] int 指明当前分页数，若为空，默认为1

isZip=[isZip] true,false 指明该接口返回数据是否需要进行压缩。若为空，默认为false

sign=[sign] string 接口的签名。若为空，表明不启用签名；后续会讲此参数必需

• currPage 需要再讨论吧，cursor 的方式不容易让翻页出现问题。
• isZip 我们的数据还需要再压缩一次？使用反向代理服务器层面对 response 进行 gzip 就可以了，默认是全开的。

1. Sticker API 中，
   /sticker/list 改为 /stickers 更好一些吧。
2. HTTP Status Code 为 500 时，内部错误 30006-30008 不用暴露给客户端，服务端自己记录就好了。