Restful API 介面設計標準以及規範

RESTful概念

理解和評估以網路為基礎的應用軟體的架構設計，得到一個功能強、效能好、適宜通訊的架構。REST指的是一組架構約束條件和原則。" 如果一個架構符合REST的約束條件和原則，我們就稱它為RESTful架構。

REST本身並沒有創造新的技術、元件或服務，而隱藏在RESTful背後的理念就是使用Web的現有特徵和能力， 更好地使用現有Web標準中的一些準則和約束。雖然REST本身受Web技術的影響很深， 但是理論上REST架構風格並不是繫結在HTTP上，只不過目前HTTP是唯一與REST相關的範例。 所以我們這裡描述的REST也是通過HTTP實現的REST。

RestfulAPI 導圖

理解RESTful

要理解RESTful架構，需要理解Representational State Transfer這個片語到底是什麼意思，它的每一個詞都有些什麼涵義。我們圍繞資源展開討論，從資源的定義、獲取、表述、關聯、狀態變遷等角度，列舉一些關鍵概念並加以解釋。

• 資源與URI
• 統一資源介面
• 資源的表述
• 資源的連結
• 狀態的轉移

資源與URI

URI 表示資源，資源一般對應伺服器端領域模型中的實體類

• URI 是地址也是資源
• URI裡邊帶上版本號、字尾來區分表述格式
• 必備約定
  • 用名詞、不用動詞
  • 層級結構明確、用/來表示
  • 用?用來過濾資源

統一資源介面

標準HTTP方法包含：GET、POST、PUT、DELETE、Patch，他們的使用功能如下列表所示

Get方法執行流程原理如下所示

Put 方法執行流程圖如下所示

安全性和冪等性

• 1、安全性：不會改變資源狀態，可以理解為唯讀的；
• 2、冪等性：執行1次和執行N次，對資源狀態改變的效果是等價的。

介面	安全性	冪等性
GET	√	√
POST	×	×
PUT	×	√
DELETE	×	√

安全性和冪等性均不保證反覆請求能拿到相同的response。以 DELETE 為例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。

資源的表述

什麼是資源？什麼是表述？

就本質而言，任何足夠重要並被參照的事物都可以是資源。如果你的使用者「想要建立指向它的超文字連結，指出或者反對關於它的斷言，獲取或者快取它的表述，共另外的表述參照它的全部或者部分，給它增加註釋資訊，或者對它執行某些操作」，（源自《全球資訊網的架構》），你都應該將它定義為資源。

每個資源必須擁有URL，在web上，我們使用URL來為每個資源提供一個全球唯一的地址，將一個事物賦以URL，它就會成為一個資源。

石榴可以是一個資源，但是你不可能通過網際網路傳輸它，資料庫中的一條記錄可以是一個資源，並且可以通過網際網路傳輸。

當用戶端對一個資源發起一個Get請求的時候，伺服器會以一種有效的方式提供一個採集了資源資訊的檔案作為迴應。這種資源資訊的檔案就是一種表述，一種以機器可讀的方式對資源當前的狀態進行說明

資源有多重表述

一個資源可以有多種表述。比如，有的資源可以有整體概括性的表述，也可以有面面俱到的詳細表述，又或者可能以JSON格式或者XML格式來表述同一個資源。

資源的連線

我們知道REST是使用標準的HTTP方法來操作資源的，但僅僅因此就理解成帶CURD的Web資料庫架構就太過於簡單了。

這種反模式忽略了一個核心概念："超媒體即應用狀態引擎（hypermedia as the engine of application state）"。 超媒體是什麼?

當你瀏覽Web網頁時，從一個連線跳到一個頁面，再從另一個連線跳到另外一個頁面，就是利用了超媒體的概念：把一個個把資源連結起來.

要達到這個目的，就要求在表述格式裡邊加入連結來引導使用者端。在《RESTful Web Services》一書中，作者把這種具有連結的特性成為連通性。下面我們具體來看一些例子。

下面展示的是github獲取某個組織下的專案列表的請求，可以看到在響應頭裡邊增加Link頭告訴使用者端怎麼存取下一頁和最後一頁的記錄。 而在響應體裡邊，用url來連結專案所有者和專案地址。

上面的例子展示瞭如何使用超媒體來增強資源的連通性。很多人在設計RESTful架構時，使用很多時間來尋找漂亮的URI，而忽略了超媒體。所以，應該多花一些時間來給資源的表述提供連結，而不是專注於"資源的CRUD"。

狀態的轉移

存取一個網站，就代表了使用者端和伺服器的一個互動過程。在這個過程中，勢必涉及到資料和狀態的變化；

網際網路通訊協定HTTP協定，是一個無狀態協定。這意味著，所有的狀態都儲存在伺服器端。因此，如果使用者端想要操作伺服器，必須通過某種手段，讓伺服器端發生"狀態轉化"（State Transfer）。而這種轉化是建立在表現層之上的，所以就是"表現層狀態轉化"；

使用者端用到的手段，只能是HTTP協定。具體來說，就是HTTP協定裡面，四個表示操作方式的動詞：GET、POST、PUT、DELETE。它們分別對應四種基本操作：GET用來獲取資源，POST用來新建資源（也可以用於更新資源），PUT用來更新資源，DELETE用來刪除資源；

博主GitHub地址

https://github.com/yuyue5945

關注公眾號不迷路