Restful API 的设计规范

转自：http://blog.csdn.net/yue7603835/article/details/52536497

URI

URI （Uniform Resource Identifier，统一资源标识符)，资源一般对应服务器端领域模型中的实体类。

URI规范

1. 不用大写;
2. 用中杠-不用下杠_;
3. 参数列表要encode;
4. URI中的名词表示资源集合，使用复数形式。

资源集合 vs 单个资源

URI表示资源的两种方式：资源集合、单个资源。

1. 资源集合：

/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物

2. 单个资源：

/zoos/1 //id为1的动物园
/zoos/1;2;3 //id为1，2，3的动物园

避免层级过深的URI

/在uri中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。
过深的导航容易导致uri膨胀，不易维护，如:
GET /zoos/1/areas/3/animals/4。
尽量使用查询参数代替路径中的实体导航，如:
GET /animals?zoo=1&area=3；

对Composite资源的访问

服务器端的组合实体必须在uri中通过父实体的id导航访问。
组合实体不是first-class的实体，它的生命周期完全依赖父实体，它是无法独立存在的，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无id。一个常见的例子是 User — Address，Address是对User表中zipCode，country，city三个字段的简单抽象，无法独立于User存在。必须通过User索引到Address：

GET /user/1/addresses    //id为1的用户的地址

Request

HTTP方法

通过标准HTTP方法对资源CRUD：
GET：查询

GET /zoos    //查询所有动物园
GET /zoos/1    //查询id为1的动物园
GET /zoos/1/employees    //查询id为1的动物园的所有员工
GET /zoos/1/employees/1    //查询id为1的动物园的1号员工

POST：创建单个资源。POST一般向“资源集合”型uri发起

POST /animals  //新增动物
POST /zoos/1/employees //为id为1的动物园雇佣员工

PUT：更新单个资源（全量），客户端提供完整的更新后的资源。与之对应的是 PATCH，PATCH 负责部分更新，客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起

PUT /animals/1
PUT /zoos/1

DELETE：删除

DELETE /zoos/1/employees/2    //删除id为1的动物园的2号员工
DELETE /zoos/1/employees/2;4;5    //删除id为1的动物园的2,4,5号员工
DELETE /zoos/1/animals  //删除id为1的动物园内的所有动物

安全性和幂等性

安全性：不会改变资源状态，可以理解为只读的；
幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。

	安全性	幂等性
get	√	√
post	×	×
put	×	√
delete	×	√

安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例，第一次DELETE返回200表示删除成功，第二次返回404提示资源不存在，这是允许的。

复杂查询

查询可以捎带以下参数：

	实例	备注
过滤条件	?type=1&age=16	允许一定的uri冗余，如/zoos/1与/zoos?id=1
排序	?sort=age,desc
投影	?whitelist=id,name,email
分页	?limit=10&offset=3

Format

只用以下常见的3种body format：

1. Content-Type: application/json；spring mvc用@RequestBody解析成对象

POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24

{
  "name": "Gir",
  "animalType": "12"
}

2. Content-Type: application/x-www-form-urlencoded (浏览器POST表单用的格式，@RequestBody不能解析)

POST /login HTTP/1.1
Host: example.com
Content-Length: 31
Accept: text/html
Content-Type: application/x-www-form-urlencoded

username=root&password=Zion0101

3. multipart/form-data; boundary=----WebKitFormBoundaryITio08aDVqufJd9L(表单有文件上传时的格式)

Content Negotiation

资源可以有多种表示方式，如json、xml、pdf、excel等等，客户端可以指定自己期望的格式，通常有两种方式：

1. http header Accept：
   Accept:application/xml;q=0.6,application/atom+xml;q=1.0
2. uri中加文件后缀
   /zoo/1.json

Response

1. 不要包装：
   response 的 body 直接就是数据，不要做多余的包装。错误示例：

{
    "success":true,
    "data":{"id":1,"name":"xiaotuan"},
}

正确示例:

{
  "id":1,
  "name":"xiaotuan"
}

2. 各HTTP方法成功处理后的数据格式

	response 格式
GET	单个对象、集合
POST	新增成功的对象
PUT/PATCH	更新成功的对象
DELETE	空