(完整word版)RESTful-API设计规范.doc

API规范

技术部代码规范

API设计规范

V1.0

总览

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

定义和术语

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

HYPERLINK"http://www.ruanyifeng.com/blog/2014/05/restful_api.html"http://www.ruanyifeng.com/blog/2014/05/restful_api.html

HYPERLINK"http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html"http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html

规范内容
2.1版本

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

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

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

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

2.3过滤（供参考）
?page=2&pageSize=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
2.4HTTP动词规范
常用的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)