RESTful API 规范

转载自《阮一峰的网络日志》 http://www.ruanyifeng.com/blog/2014/05/restful_api.html。

RESTful是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

1. 协议

RESTful API 总是使用 HTTPS协议进行通信。

2. 域名

应该尽量将 API 部署在专用域名下，例如：

https://api.example.com

3. 版本

应该将 API 版本号放入 URL，例如：

https://api.example.com/v1/

也可以将版本号放在 HTTP Header 信息中，但不如放入 URL 中方便和直观。

4. 实体

在 RESTful 架构中，每个地址代表一种资源，所以地址中不能有动词，只能有名词，且实体名称均以复数形式表示。例如：

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

5. 动词

后端逻辑总是能对应到对数据库的增删改查上，其恰好与 GET、POST、PUT、DELETE 四种 HTTP Method 对应。因此，REST 使用 HTTP Method 标示操作类型，减少在 URL 中显示指明操作类型的情况。例如，使用 GET /users 代替 GET /users/qry。例如：

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

6. 状态码

REST 使用 HTTP 状态码标示请求的执行结果，而非正文中的部分字段。

200 OK - [GET]：服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
202 Accepted - [*]：请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）
403 Forbidden - [*] 表示用户得到授权，但是访问是被禁止的
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作
406 Not Acceptable - [GET]：用户请求的格式不可得
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功

修订记录：

日期	版本号	作者	修订内容	备注
2019-7-14	1.0	moonspirit	创建文档