RESTful-API设计规范.doc

API规范
技术部代码规范

API设计规范

V1.0

1. 总览

1.1. 前言
为了开发人员快速理解，掌握API的含义，能望文生义，提高沟通交流效率。
1.2. 为什么要API统一规范？
阅读方便、爽，因为遇到和自己不同的书写和规范时会感觉很不爽。同时也是考虑到API安全问题，所有的API开发必须遵循oAuthor协议。
1.3. 适用人员
API代码开发和代码Review的相关人员。
1.4. 范围

1.5. 定义和术语

不可使用- 规范中涉及的不可使用的内容，坚决不能使用
建议使用- 规范中涉及的建议使用的内容，结合实际业务需求，开发习惯，最大程度的符合规范。
必须使用- 规范中涉及的必须使用的内容，所有研发人员严格按照规范进行开发
1.6. 相关引用文档

6
2. 规范内容
2.1 版本

应该将API的版本号放入URL。

示例 ：
https://example.org/api/v1/

2.2 URI定义
路径又称"终点"（endpoint），表示API的具体网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
Example ：以动物园集合为例

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息
DELETE /zoos/ID：删除某个动物园

2.3 过滤 （供参考）
l ?page=2&pageSize=100：指定第几页，以及每页的记录数。
l ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
l ?animal_type_id=1：指定筛选条件
2.4 HTTP 动词规范
常用的HTTP动词有下面4个（对应SQL的命令）
Ø GET（SELECT）：从服务器取出资源（一项或多项）。
Ø POST（CREATE）：在服务器新建一个资源。
Ø PUT（UPDATE）：在服务器更新资源。
Ø DELETE（DELETE）：从服务器删除资源。

2.5 请求格式
请求数据格式统一json

请求数据格式如下：
wuBaNfJson= {
"params": {
"key1": "value1",
"key2": "value2"
},
"secret": "123456780233FA31AD94AA59CFA65305",
"timestamp": 20151101095440000000,
"sign": "E981702AF260F37FCCD7D60FD19AAEA7"
}

2.6 返回格式
返回数据格式统一JSON

数据结果如下：

{
"errcode":0,//提示码
"errmsg":"ok", //提示信息
"data": {接口返回的数据} // 请求失败返回可以为空，成功为非空
}
Errcode 状态码汇总表

状态码
说明
0
表示成功
-1
表示系统繁忙
101
表示解析JSON内容错误
102
表示签名错误
500
表示系统错误

2.7 签名算法

意义 ：防止关键业务数据被纂改，保证数据的安全性与完整性。
算法：
Md5(secret+wubanf_param_json+timestamp)