2.3.1 Web API -- REST && RESTful
- 什么是 REST，什么是 RESTful
- RESTful API 设计
- RESTful 成熟度模型
什么是 REST，什么是 RESTful
理解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
| 资源 | 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 设计
RESTful API 设计指南：http://www.ruanyifeng.com/blog/2014/05/restful_api.html
基本概念
- 版本 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 成熟度模型
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。此外，由于资源信息中包含可允许操作的链接，客户端无需猜测在资源的当前状态下执行何种操作。