前言
近十年，前端高速发展，整个互联网应用经历了从轻客户端到重客户端的变化，随着前端规模越来越大，交互越来越复杂，前后端分离的设计开始流行。
移动互联网时代的到来，前端开始泛指各种终端和 web 前端，服务端为多终端提供服务已然成常态。
前后端分离后，前端和后端通过双方协商好的 API 进行交互，所以设计一套友好的 API 尤其重要。
RESTful 就是目前最流行的前后端交互 API 设计范式。
RESTful 释义
顾名思义，先看一下 RESTful 的单词拆解:
RESTful = Resources + Representation + State + Transfer + ful
我的理解是， RESTful 是指具有 资源表现层 和 状态转换 的架构设计。
资源(Resources)
资源，是指服务端向外提供的服务实体。
资源是一个抽象的概念，可以是应用程序对象、数据库记录、算法等等。每一个资源用一个 URI 来唯一标识，客户端通过这个标识对资源进行访问、操作或请求服务。
表现层(Representation)
表现层，是指资源的表现形式。
一个资源可以有多种表现形式。例如，文本数据可以用 XML 格式、JSON 格式表现，甚至可以用二进制格式表示；图片可以用 JPG 格式表现，也可以用 PNG 格式表现。
状态(State)
状态，是指资源的某种状态。
一个资源可能有多种状态。例如，资源空闲的、占用的、共享的、存在的、不存在的等。
转化(Transfer)
转化，是指对资源的操作行为。
转化的行为包括两种:
- 资源表现层的转化
- 资源状态的转化
小结
RESTful 是一种抽象的、与具体程序语言和网络协议无关的网络服务系统的架构样式。
它把在服务器端的数据和功能设计成各种的资源，并且通过 URI 定位资源、转化资源表现和状态的一种服务架构设计。
RESTful WEB
REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。
目前 RESTful 应用最多的是在 web 服务，在 RESTful Web 服务中，每个资源都有一个地址(URL)。资源是方法调用的目标，方法列表对所有资源都是一样的。这些方法是 Http 标准方法，如 HTTP GET、POST、PUT、DELETE 等。
下面来描述一下 RESTful Web API 的一些设计原则。
通信协议
数据传输，安全第一。
HTTPS 协议要优于 HTTP 协议。
API 的根 URL
API 的根 URL 很重要，它应该设计成可以轻松区别于其他非 API 的 URL。
最好的做法是将 API 部署在专有的域名下。
https://api.example.com
退而求其次，分配一个域名一级目录给 API。
https://example.org/api/
版本信息
为了 API 演变和兼容，为 API 加入版本信息是明智之举。
应该为 API 设定版本号，并把版本号信息加入到 API 的根 URL 的下一级路径。
https://api.example.com/v1/
或
https://example.org/api/v1/
URL 末端
API 的根 URL + 版本信息 + URL 末端 = 资源位置
URL 末端最终明确指定了一个资源或一种资源的集合。URL 末端中不应该出现动词，只能是名词。
举个例子，有一组 API 提供公司员工的信息。
那么，获取所有员工信息，末端应该设计成 /employees, 即:
https://api.example.com/v1/employees
获取员工编号 007 员工的信息，末端应该设计成 /employees/007, 即:
https://api.example.com/v1/employees/007
操作资源
资源的操作无外乎增、删、改、查，对应即是 HTTP 的各个操作方法。
HTTP的操作方法在 RESTful 中有各自的语义，理解它们的语义至为重要。
| 方法 | 语义 | 例子 | 说明 |
|---|---|---|---|
| GET | 选择、获取 | GET /employees/007 |
获取编号 007 员工的信息 |
| POST | 新建 | POST /employees |
新建一个员工的信息 |
| PUT | 更新(完整) | PUT /employees/007 |
更新编号 007 员工的全部信息，客户端提供该员工的全部信息 |
| PATCH | 更新(局部) | PATCH /employees/007 |
更新编号 007 员工的部分信息，客户端只提供该员工的部分信息 |
| DELETE | 删除 | DELETE /employees/007 |
删除编号 007 员工的信息 |
| HEAD | 获取(元数据) | HEAD /employees/007 |
获取编号 007 员工的元数据，如员工数据的哈希值或最后修改时间 |
| OPTIONS | 获取(权限信息) | OPTIONS /employees/007 |
获取客户端能编号 007 员工进行哪些操作，即操作的权限 |
本章中，自此以上讲述的都是如何描述"资源(Resources)"，而这小节讲述的是"转化(Transfer)"，转化资源的状态。
另外，转化还包括资源的"表现层(Representation)"，它是通过 HTTP 头部 Content Type 指定的。
过滤资源
如果资源很多，通常你不会希望服务端一次性全部的数据，API 应该提供过滤资源的能力。
这里资源过滤依靠 URL 的查询参数，通常放置在 GET 请求的URL中。
- ?limit=10: 限制返回的资源数量
- ?offset=10: 指定返回的资源的开始位置
- ?sortby=name&order=asc: 对资源按特定属性进行排序
状态码
状态码用以反映资源的操作结果或所处状态。
HTTP 状态码本身是具有语义的，这刚好配对了 RESTful 的状态。
以下列举常用的状态码:
| 状态码 | 语义 | 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 | * | 表示用户得到授权（与401错误相对），但是访问是被禁止的 |
| 404 | NOT FOUND | * | 请求对应的资源不存在 |
| 406 | Not Acceptable | GET | 用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）, 即未支持的表现层 |
| 410 | Gone | GET | 用户请求的资源被永久删除，且不会再得到的 |
| 422 | Unprocesable entity | POST/PUT/PATCH | 当创建一个对象时，发生一个验证错误 |
错误处理
如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值。
{
error: "param error"
}
返回结果
对于不同操作方法和操作对象(集合或个体)，服务器返回的结果应该符合以下规范。
| 示例 | 返回 |
|---|---|
| GET /collection | 返回资源对象的列表（数组） |
| GET /collection/resource | 返回单个资源对象 |
| POST /collection | 返回新生成的资源对象 |
| PUT /collection/resource | 返回完整的资源对象 |
| PATCH /collection/resource | 返回完整的资源对象 |
| DELETE /collection/resource | 返回一个空文档 |
另外，返回的数据格式(Representation)应该尽量使用JSON。
最后
在 RESTful WEB 的实现中，使用 URL 定位资源，HTTP 方法操作资源，使得语义明确、结构清晰、易于理解和扩展。
RESTful 的这些优势，使得它成为了目前最流行的一种互联网服务架构。
附录
该文主要参考:
