Restful API 的设计规范
1. URI
URI规范
资源调集 vs 单个资源
制止层级过深的URI
对Composite资源的访谒
2. Request
HTTP要领
安适性和幂等性
庞大盘问
Bookmarker
Format
Content Negotiation
6. Response
分页response
7. 错误措置惩罚惩罚
8. 处事型资源
9. 异步任务
10. API的演进
版本
URI掉效
11. 安适
参考文档
本文总结了 RESTful API 设计相关的一些原则，只笼罩了常见的场景。有些法则只是针对本身项目而言，并非其他做法都是错误的。
1. URI
URI 暗示资源，资源一般对应处事器端范围模型中的实体类。
URI规范
不用大写；
用中杠 - 不用下杠 _ ；
参数列表要encode；
URI中的名词暗示资源调集，使用复数形式。
资源调集 vs 单个资源
URI暗示资源的两种方法：资源调集、单个资源。
资源调集：
/zoos //所有动物园 /zoos/1/animals //id为1的动物园中的所有动物
单个资源：
/zoos/1 //id为1的动物园 /zoos/1;2;3 //id为1，2，3的动物园制止层级过深的URI
/ 在url中表达层级，用于 按实体关联关系进行东西导航 ，一般按照id导航。
过深的导航容易导致url膨胀，不易维护，如 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
2. RequestHTTP要领
通过标准HTTP要领对资源CRUD：
GET：盘问
GET /zoos GET /zoos/1 GET /zoos/1/employees
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 DELETE /zoos/1/employees/2;4;5 DELETE /zoos/1/animals //删除id为1的动物园内的所有动物
HEAD / OPTION 用的不久不多，就不久不多解释了。
安适性和幂等性
安适性 ：不会转变资源状态，可以理解为只读的；
幂等性 ：执行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
Bookmarker
经常使用的、庞大的盘问标签化，降低维护本钱。
如：
GET /trades?status=closed&sort=created,desc
快捷方法：
GET /trades#recently-closed 或者 GET /trades/recently-closedFormat
只用以下常见的3种body format：
Content-Type: application/json POST /v1/animal HTTP/1.1 Host: api.example.org Accept: application/json Content-Type: application/json Content-Length: 24 { "name": "Gir", "animalType": "12" }