.NET 雲原生架構師訓練營（子產品二 基礎鞏固 REST && RESTful）--學習筆記2.3.1 Web API -- REST && RESTful

2.3.1 Web API -- REST && RESTful

• 什麼是 REST，什麼是 RESTful
• RESTful API 設計
• 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 設計指南：

http://www.ruanyifeng.com/blog/2014/05/restful_api.html

基本概念

• 版本 versioning
• 路徑 endpoint
• 動詞 verb
• 過濾資訊 filtering
• status code
• error handling

内容		狀态碼	結果	HTTP動詞
擷取問題清單	/api/v1/question	200	傳回具體的資源結果	GET
建立問題		201	傳回建立的資源	POST
擷取單個問題	/api/v1/question/1001	200/404	傳回資源/不存在
修改問題			傳回修改的資料	PUT
				PATCH
删除問題		204	删除成功	DELETE

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。此外，由于資源資訊中包含可允許操作的連結，用戶端無需猜測在資源的目前狀态下執行何種操作。