REST

## 1 含义

1. REST 这个词，是**Roy Thomas Fielding 在他 2000 年的博士论文中提到的**。
2. Fielding 将他对**互联网软件的架构原则**，**定义为 REST**（Representational State Transfer），即**表现层状态转化**，如果**一个架构符合 REST 原则**，就**称它为 RESTful 架构**。
3. 要理解 RESTful 架构，最好的方法就是去理解 Representational State Transfer 这个词组到底是什么意思，他的每一个词代表了什么涵义，如果我们把这个名称搞懂了，也就不难体会 REST 是一种什么样的设计了。
4. REST 架构主要有三个关键词，分别是**资源**（Resources）、**表现层**（Representation）、**状态转化**（State Transfer）：
   1. **资源**：
      1. REST 的名称表现层状态转化中，省略了主语，**表现层其实指的是资源的表现层**。
      2. 所谓**资源**，就**是网络上的一个实体**，**或者说是网络上的一个具体信息**，**他可以是一段文本**、**一张图片**、**一首歌曲**、**一种服务**，总之就**是一个具体的存在**。
      3. 我们**可以用一个 URI**（统一资源标识符）**指向他**，**每种资源对应一个特定的 URI**，**要获取这个资源**，**访问他的 URI 就可以**，因此**URI 就成了每一个资源的地址或独一无二的标识符**。
   2. **表现层**：
      1. **资源是一种信息实体**，**他可以有多种外在表现形式**，我们把**资源具体呈现出来的形式**，叫做他的**表现层**。
      2. 比如，**文本可以用 TXT 格式表现**，**也可以用 HTML**、**XML**、**JSON 格式表现**，**甚至可以采用二进制格式**。
      3. **URI 只代表资源的位置**，**他的具体表现形式**，**应该在 HTTP 请求的头信息中用 Accept 和 Content-Type 字段指定**，**这两个字段才是对表现层的描述**。
   3. **状态转化**：
      1. **访问一个网站**，就**代表了客户端和服务器的一个互动过程**，**在这个过程中**，**势必涉及到数据和状态的变化**。
      2. 互联网通信协议**HTTP 协议**，**是一个无状态的协议**，这意味着，**所有的状态都保存在服务器端**，因此，**如果客户端想要操作服务器**，**必须通过某种手段**，**让服务器端发生状态转化**，而**这种转化是建立在表现层之上的**，所以就是**表现层状态转化**。
5. 综合上面的解释，我们总结一下什么是 RESTful 架构：
   1. **每一个 URI 代表一种资源**。
   2. **客户端和服务器之间**，**传递这种资源的某种表现层**。
   3. **客户端通过四个 HTTP 动词**（GET 获取资源、POST 新建或更新资源、PUT 更新资源、DELETE 删除资源），**对服务器端资源进行操作**，**实现表现层状态转化**。

## 2 特点

1. **客户-服务器**：

1. 在REST风格中，最基本的要求是**对于一个程序来说**，**应当分离用户接口和数据存储**，**改善用户接口跨平台迁移的可移植性**，同时**简化服务器组件**，**改善系统的可伸缩性**，**客户端负责与用户之间的交互处理**，而**服务器端则实现数据存储以及相关的业务逻辑**。
   2. **对于服务器端**，**完整的系统大部分情况下都会包含多个不同的模块**，**这些模块之间的调用也应当遵循客户-服务器模式**，**模块之间通过接口进行互相访问**。
2. **无状态**：

1. **服务端在设计接口时**，**应当设计为无状态接口**，也就是说，**服务器端不保存任何与客户端相关的状态上下文信息**，**客户端在每次调用服务端接口时**，**需要提供足够的信息**，**以供服务端完成操作**。
   2. **在无状态的设计中**，**服务端减少了保存客户端相关上下文数据**，因此，**一方面服务端能够更加容易的实现动态扩展**，**而不至于影响客户端使用**，**另一方面则减少了服务端从故障中恢复的任务量**。
3. **缓存**：

1. **根据接口的实际情况**，**应当在接口设计中增加缓存策略**，**服务端可以决定是否可以缓存当前返回的数据**，通过这种方式，**可以在一定程度上减少实际到达服务端的请求**，**从而提高网络访问性能**。
   2. **但缓存需要谨慎使用**，**缓存哪些数据**、**缓存过期时间都是需要根据实际情况进行设计**，**适当的缓存可以有效地提高系统效率**，**但是如果设计不当**，**将有可能导致大量的过期数据**，**进而影响系统运行**。
   3. 一般而言，**数据字典类数据**、**修改频率非常低的数据**、**实时性要求很低的数据等**，**这些数据可以设计一定的缓存策略**，**以提高系统运行效率**。
4. **系统分层**：

1. 在**设计系统时**，**尤其是大型系统**，通常**需要将系统按照不同的功能进行横向和纵向的分层**，例如**横向分层一般可分为交互层**、**服务层**、**数据层等**，而**纵向分层则通常按照不同的业务功能对系统进行切分**。
   2. **经过分层后**，**系统将划分为不同的模块进行独立开发部署运行**，**不同的模块可以独立进化**，**实现功能解耦**，**提高整个系统的可扩展性**。
5. **统一接口**：

1. **统一接口**，**即不同的系统模块之间的调用接口统一规范**，**使用统一的调用协议**，**统一的数据格式等**。
   2. **统一接口带来的是系统交互功能的规范化**，**接口调用与业务解耦**，**各模块独立进化**。
6. **按需代码**（可选）：

1. **按需代码允许我们灵活的发送一些看似特殊的代码给客户端**，如**JavaScript代码**。
   2. **按需代码的好处是可以减少一些代码**，**简化客户端**。

## 3 RESTful API 设计规范

1. **协议**：

1. **API 与用户的通信协议**，**总是使用 HTTPS 协议**。
2. **域名**：

1. 应该尽量**将 API 部署在专用域名之下**：

```txt
      https://api.example.com
      ```
   2. 如果**确定 API 很简单**，**不会有进一步的扩展**，**可以考虑放在主域名下**：

```txt
      https://example.org/api
      ```
3. **版本**：

1. 应该**将 API 的版本号放入 URL**：

```txt
      https://api.example.com/v1
      ```
   2. 另一种做法是，**将版本号放在 HTTP 头信息中**，但**不如放入 URL 方便直观**，**[Github](https://developer.github.com/v3/media/#request-specific-version)采用这种做法**。
4. **路径**：

1. **路径又称终点**（Endpoint），**表示 API 的具体网址**。
   2. 在 RESTful 架构中，**每个网址代表一种资源**，所以**网址中不能有动词**，**只能有名词**，而且**所用的名词往往与数据库中的表格名对应**，一般来说，**数据库中的表都是同种记录的集合**，所以**API 中的名词也应该使用复数**。
   3. 举例来说，有一个 API 提供动物园的信息，还包括各种动物和雇员的信息，则他的路径应该设计成下面这样：

```txt
      https://api.example.com/v1/zoos
      https://api.example.com/v1/animals
      https://api.example.com/v1/employees
      ```
5. **HTTP 动词**：

1. 对于**资源的具体操作类型**，**由 HTTP 动词表示**。
   2. 常见的 HTTP 动词有下面五个：

1. **GET**：从服务器**取出资源**。
      2. **POST**：在服务器**新建一个资源**。
      3. **PUT**：在服务器**更新资源**（**客户端提供改变后的完整资源**）。
      4. **PATCH**：在服务器**更新资源**（**客户端提供改变的属性**）
      5. **DELETE**：从服务器**删除资源**。
   3. 还有两个不常用的 HTTP 动词：

1. **HEAD**：**获取资源的元数据**。
      2. **OPTIONS**：**获取信息**，**关于资源的哪些属性是客户端可以改变的**。
   4. 具体的示例如下：

```txt
      GET /zoos：列出所有动物园
      POST /zoos：新建一个动物园
      GET /zoos/ID：获取某个指定动物园的信息
      PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
      PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
      DELETE /zoos/ID：删除某个动物园
      GET /zoos/ID/animals：列出某个指定动物园的所有动物
      DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
      ```
6. **过滤信息**：

1. 如果**记录数量很多**，**服务器不可能都将他们返回给用户**，API 应该**提供参数**，**过滤返回结果**。
   2. 下面是一些常见的参数：

```txt
      ?limit=10：指定返回记录的数量
      ?offset=10：指定返回记录的开始位置。
      ?page=2&per_page=100：指定第几页，以及每页的记录数。
      ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
      ?animal_type_id=1：指定筛选条件
      ```
   3. **参数的设计允许存在冗余**，即**允许 API 路径和 URL 参数偶尔有重复**，比如 `GET /zoo/ID/animals` 与 `GET /animals?zoo_id=ID` 的含义是相同的。
7. **状态码**：

1. **服务器向用户返回的状态码和提示信息**，常见的有以下一些（方括号中是该状态码对应的 HTTP 动词）：

```txt
      200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
      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] 当创建一个对象时，发生一个验证错误。
      500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
      ```
   2. 状态码的完整列表参见[10 Status Code Definitions](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)。
8. **错误处理**：

1. 如果**状态码是 4xx**，就**应该向用户返回错误信息**，一般来说，**返回的信息中将 `error` 作为键名**，**出错信息作为键值即可**，例如：

```json
      {
        error: "Invalid API key"
      }
      ```
9. **返回结果**：

1. 针对不同操作，**服务器向用户返回的结果应该符合以下规范**：

```txt
      GET /collection：返回资源对象的列表（数组）
      GET /collection/resource：返回单个资源对象
      POST /collection：返回新生成的资源对象
      PUT /collection/resource：返回完整的资源对象
      PATCH /collection/resource：返回完整的资源对象
      DELETE /collection/resource：返回一个空文档
      ```
10. **Hypermedia API**：

1. RESTful API 最好**做到 Hypermedia**，即**返回结果中提供链接**，**连向其他 API 方法**，**使得用户不查文档**，**也知道下一步应该做什么**。
    2. 比如，当用户向 `api.example.com` 的根目录发出请求，会得到这样一个文档：

```json
       {"link": { 
         "rel":   "collection https://www.example.com/zoos",
         "href":  "https://api.example.com/zoos",
         "title": "List of zoos",
         "type":  "application/vnd.yourformat+json"
       }}
       ```
    3. 上面代码表示，文档中有一个 `link` 属性，用户读取这个属性就知道下一步该调用什么 API 了：

1. `rel`：**表示这个 API 与当前网址的关系**（`collection` 关系，并给出该`collection` 的网址）。
       2. `href`：**表示 API 的路径**。
       3. `title`：**表示 API 的标题**。
       4. `type`：**表示返回类型**。
    4. **Hypermedia API 的设计被称为[HATEOAS](http://en.wikipedia.org/wiki/HATEOAS)**，Github的API就是这种设计，**访问[api.github.com](https://api.github.com)会得到一个所有可用API的网址列表**：

```json
       {
         "current_user_url": "https://api.github.com/user",
         "authorizations_url": "https://api.github.com/authorizations",
         // ...
       }
       ```
    5. 从上面可以看到，如果**想获取当前用户的信息**，**应该去访问[api.github.com/user](https://api.github.com/user)**，然后就得到了下面的结果：

```json
       {
           "message": "Requires authentication",
           "documentation_url": "https://developer.github.com/v3"
       }
       ```
    6. 上面代码表示，**服务器给出了提示信息**，**以及文档的网址**。
11. **其他**：

1. **API的身份认证应该使用[OAuth 2.0](http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html)框架**。
    2. **服务器返回的数据格式**，**应该尽量使用JSON**，**避免使用XML**。

## 参考文献

1. [深入理解什么是 RESTful API ？](https://www.jianshu.com/p/84568e364ee8)
2. [Restful 应用理解](https://juejin.cn/post/6844903792727556103)。
3. [怎样用通俗的语言解释REST，以及RESTful？](https://www.zhihu.com/question/28557115/answer/79275672)
4. [前端要知道的RESTful API架构风格](https://segmentfault.com/a/1190000020029993)。