.NET 云原生架構(gòu)師訓練營（模塊二 基礎鞏固 REST && RESTful）--學習筆記
2.3.1 Web API -- REST && RESTful
什么是 REST，什么是 RESTful
RESTful API 設計
RESTful 成熟度模型
什么是 REST，什么是 RESTful
理解RESTful架構(gòu)：https://www.ruanyifeng.com/blog/2011/09/restful.html
REST（Representational State Transfer）：表現(xiàn)層狀態(tài)轉(zhuǎn)化
RESTful：面向資源的架構(gòu)
如果一個架構(gòu)符合REST原則，就稱它為RESTful架構(gòu)。
"表現(xiàn)層"其實指的是"資源"（Resources）的"表現(xiàn)層"。
所謂"資源"，就是網(wǎng)絡上的一個實體，或者說是網(wǎng)絡上的一個具體信息。它可以是一段文本、一張圖片、一首歌曲、一種服務，總之就是一個具體的實在。
你可以用一個URI（統(tǒng)一資源定位符）指向它，每種資源對應一個特定的URI。
URI：資源的地址，至于資源的形式 URI 是不管的，但是會通過 http 請求的一些參數(shù)來做具體的返回
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 |
"資源"是一種信息實體，它可以有多種外在表現(xiàn)形式。我們把"資源"具體呈現(xiàn)出來的形式，叫做它的"表現(xiàn)層"（Representation）。
表現(xiàn)形式：JSON/XML
比如，文本可以用txt格式表現(xiàn)，也可以用HTML格式、XML格式、JSON格式表現(xiàn)，甚至可以采用二進制格式；圖片可以用JPG格式表現(xiàn)，也可以用PNG格式表現(xiàn)。
互聯(lián)網(wǎng)通信協(xié)議HTTP協(xié)議，是一個無狀態(tài)協(xié)議。這意味著，所有的狀態(tài)都保存在服務器端。
因此，如果客戶端想要操作服務器，必須通過某種手段，讓服務器端發(fā)生"狀態(tài)轉(zhuǎn)化"（State Transfer）。而這種轉(zhuǎn)化是建立在表現(xiàn)層之上的，所以就是"表現(xiàn)層狀態(tài)轉(zhuǎn)化"。
狀態(tài)轉(zhuǎn)化
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
| 內(nèi)容 | URI | 狀態(tài)碼 | 結(jié)果 | HTTP動詞 |
|---|---|---|---|---|
| 獲取問題列表 | /api/v1/question | 200 | 返回具體的資源結(jié)果 | GET |
| 創(chuàng)建問題 | /api/v1/question | 201 | 返回創(chuàng)建的資源 | POST |
| 獲取單個問題 | /api/v1/question/1001 | 200/404 | 返回資源/不存在 | GET |
| 修改問題 | /api/v1/question/1001 | 201 | 返回修改的數(shù)據(jù) | PUT |
| 修改問題 | /api/v1/question/1001 | 201 | 返回修改的數(shù)據(jù) | PATCH |
| 刪除問題 | /api/v1/question/1001 | 204 | 刪除成功 | DELETE |
RESTful 成熟度模型
Level 0：
本層級的 Web 服務只是使用 HTTP 作為傳輸方式，實際上只是遠程方法調(diào)用（RPC）的一種具體形式。SOAP 和 XML-RPC 都屬于此類。
Level 1：
Level 1 層級的 API 引入了資源的概念。要執(zhí)行對資源的操作，客戶端發(fā)出指定要執(zhí)行的操作和任何參數(shù)的 POST 請求。
Level 2：
Level 2 層級的 API 使用 HTTP 語法來執(zhí)行操作，譬如 GET 表示獲取、POST 表示創(chuàng)建、PUT 表示更新。如有必要，請求參數(shù)和主體指定操作的參數(shù)。這能夠讓服務影響 web 基礎設施服務，如緩存 GET 請求。
Level 3：
Level 3 層級的 API 基于 HATEOAS（Hypertext As The Engine Of Application State）原則設計，基本思想是在由 GET請求返回的資源信息中包含鏈接，這些鏈接能夠執(zhí)行該資源允許的操作。例如，客戶端通過訂單資源中包含的鏈接取消某一訂單，GET 請求被發(fā)送去獲取該訂單。HATEOAS 的優(yōu)點包括無需在客戶端代碼中寫入硬鏈接的 URL。此外，由于資源信息中包含可允許操作的鏈接，客戶端無需猜測在資源的當前狀態(tài)下執(zhí)行何種操作。