.NET 云原生架构师训练营（模块二 基础巩固 REST && RESTful）--学习笔记

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。此外，由于资源信息中包含可允许操作的链接，客户端无需猜测在资源的当前状态下执行何种操作。

课程链接

https://appsqsyiqlk5791.h5.xiaoeknow.com/v1/course/video/v_5f39bdb8e4b01187873136cf?type=2

本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。

欢迎转载、使用、重新发布，但务必保留文章署名 郑子铭 （包含链接： http://www.cnblogs.com/MingsonZheng/ ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。

如有任何疑问，请与我联系 (MingsonZheng@outlook.com) 。