# 模块二 基础巩固 REST && RESTful

## 2.3.1 Web API -- REST && RESTful <a href="#id-231-web-api----rest--restful" id="id-231-web-api----rest--restful"></a>

* 什么是 REST，什么是 RESTful
* RESTful API 设计
* RESTful 成熟度模型

### 什么是 REST，什么是 RESTful <a href="#shen-me-shi-rest-shen-me-shi-restful" id="shen-me-shi-rest-shen-me-shi-restful"></a>

理解RESTful架构：<https://www.ruanyifeng.com/blog/2011/09/restful.html>

REST（Representational State Transfer）：表现层状态转化

RESTful：面向资源的架构

如果一个架构符合REST原则，就称它为RESTful架构。

"表现层"其实指的是"资源"（Resources）的"表现层"。

所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。

你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。

URI：资源的地址，至于资源的形式 URI 是不管的，但是会通过 http 请求的一些参数来做具体的返回

baseUri: [https://www.dotnetlives.com](https://www.dotnetlives.com/)

| 资源 | Resource | URI                                    |
| -- | -------- | -------------------------------------- |
| 问题 | Question | <https://www.dotnetlives.com/question> |
| 计划 | Plan     | <https://www.dotnetlives.com/plan>     |
| 项目 | Project  | <https://www.dotnetlives.com/project>  |
| 奖励 | Award    | <https://www.dotnetlives.com/award>    |

"资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现层"（Representation）。

表现形式：JSON/XML

比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。

互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。

因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。

状态转化

* Get
* Post
* Put
* Delete

ASP .NET Core Web Api 是一个 RESTful Web 应用框架

### RESTful API 设计 <a href="#restfulapi-she-ji" id="restfulapi-she-ji"></a>

RESTful API 设计指南：<http://www.ruanyifeng.com/blog/2014/05/restful_api.html>

#### 基本概念 <a href="#ji-ben-gai-nian" id="ji-ben-gai-nian"></a>

* 版本 versioning
* 路径 endpoint
* 动词 verb
* 过滤信息 filtering
* status code
* error handling

| 内容     | URI                   | 状态码     | 结果        | HTTP动词 |
| ------ | --------------------- | ------- | --------- | ------ |
| 获取问题列表 | /api/v1/question      | 200     | 返回具体的资源结果 | GET    |
| 创建问题   | /api/v1/question      | 201     | 返回创建的资源   | POST   |
| 获取单个问题 | /api/v1/question/1001 | 200/404 | 返回资源/不存在  | GET    |
| 修改问题   | /api/v1/question/1001 | 201     | 返回修改的数据   | PUT    |
| 修改问题   | /api/v1/question/1001 | 201     | 返回修改的数据   | PATCH  |
| 删除问题   | /api/v1/question/1001 | 204     | 删除成功      | DELETE |

### RESTful 成熟度模型 <a href="#restful-cheng-shou-du-mo-xing" id="restful-cheng-shou-du-mo-xing"></a>

Level 0：

本层级的 Web 服务只是使用 HTTP 作为传输方式，实际上只是远程方法调用（RPC）的一种具体形式。SOAP 和 XML-RPC 都属于此类。

Level 1：

Level 1 层级的 API 引入了资源的概念。要执行对资源的操作，客户端发出指定要执行的操作和任何参数的 POST 请求。

Level 2：

Level 2 层级的 API 使用 HTTP 语法来执行操作，譬如 GET 表示获取、POST 表示创建、PUT 表示更新。如有必要，请求参数和主体指定操作的参数。这能够让服务影响 web 基础设施服务，如缓存 GET 请求。

Level 3：

Level 3 层级的 API 基于 HATEOAS（Hypertext As The Engine Of Application State）原则设计，基本思想是在由 GET请求返回的资源信息中包含链接，这些链接能够执行该资源允许的操作。例如，客户端通过订单资源中包含的链接取消某一订单，GET 请求被发送去获取该订单。HATEOAS 的优点包括无需在客户端代码中写入硬链接的 URL。此外，由于资源信息中包含可允许操作的链接，客户端无需猜测在资源的当前状态下执行何种操作。