1、什么是REST？

要想更清楚地了解restful api是什么，我們還需要簡單了解下REST是什么？它是一種軟件架構，決定了 API 的工作條件。2000年，羅伊·菲爾丁提出了代表狀態轉移（REST）作為設計網絡服務的架構方法，REST 最初作為管理復雜網絡（例如互聯網）上的通信的指南而建立。使用者可以使用基于 REST 的架構為高性能和可靠的大規模通信提供支持；可以輕松應用和修改此種架構，為任何 API 系統帶來可見性和跨平臺可能性。
REST架構是一種基于超媒體構建分布式系統的建筑風格，它獨立于任何底層協議，不一定與HTTP綁定，唯一的要求是它們要符合以下六種 架構約束(架構約定)：

1. 統一接口。 無論請求來自何處，對同一資源發出的所有 API 請求都應該看起來相同。 REST API 應確保同一條數據（例如用戶的姓名或電子郵件地址）僅屬于一個統一資源標識符 (URI)。 資源不應過大，但應包含客戶可能需要的每一條信息。
2. 客戶端/服務器解耦。 在 REST API 設計中，客戶端和服務器的應用程序必須彼此完全獨立。 客戶端應用程序應該知道的唯一信息是所請求資源的 URI；它不能以任何其他方式與服務器應用程序交互。 同樣，除了通過 HTTP 將客戶端應用程序傳遞到所請求的數據外，服務器應用程序不應修改客戶端應用程序。
3. 無狀態。 REST API 是無狀態的，這意味著每個請求都需要包含處理它所需的全部信息。 換句話說，REST API 不需要任何服務器端會話。 不允許服務器應用程序存儲與客戶端請求相關的任何數據。
4. 可緩存性。 如果可能，資源應該可以在客戶端或服務器端緩存。 服務器響應還需要包含有關是否允許對交付的資源進行緩存的信息。 目標是提高客戶端的性能，同時增強服務器端的可擴展性。
5. 分層系統架構。 在 REST API 中，調用和響應都會經過多個不同的層。 根據經驗，不要假設客戶端和服務器應用程序直接連接到彼此。 通信環路中可能包含多個不同的中介服務器。 需要設計 REST API，讓客戶端和服務器都無法判斷它是與最終應用程序還是中介服務器進行通信。
6. 按需編碼（可選）。 REST API 通常發送靜態資源，但在某些情況下，響應也可以包含可執行代碼（例如 Java 小程序）。 在這些情況下，代碼只應按需運行。

簡而言之，在REST架構風格中，數據和功能被視為資源，并使用統一資源標識符（URI）進行訪問。

2、Rest api 是什么？

了解了REST是什么，我們再來了解下Rest api 是什么？一般情況下，遵循 REST 架構風格的 API 稱為 REST API。因為REST 是一組架構規范，并非協議或標準，API 開發人員可以采用各種方式實施 REST。例如，當客戶端通過 REST API 提出請求時，它會將資源狀態表述傳遞給請求者或終端。該信息或表述通過 HTTP 以下列某種格式傳輸：JSON（Javascript 對象表示法）、HTML、XLT、Python、PHP 或純文本。

由于JSON 能被人和機器‘讀’，在當下開放API環境及大部分企業內部應用中，實施REST API時，默認都采用REST約定+HTTP+JSON，這種組合已經是一種事實上的標準。 下文及本網站提到的REST API、[[wiki:http-api|HTTP API]、Web API，在具體實施時，一般都是‘__REST約定+HTTP+JSON’標準的API__。

需要注意的地方： RESTful API采用HTTP時，HTTP頭和參數、 HTTP 方法也很重要，因為其中包含了請求的元數據、授權、統一資源標識符（URI）、緩存、cookie 等重要標識信息。有請求頭和響應頭，每個頭都有自己的 HTTP 連接信息和狀態碼。在《RESTfal API 設計》一文中會重點講這部分內容的設計。

與Rest api 是什么？相關的一些基本概念：

? REST API 是什么- Payload
? REST API 是什么 – HTTP Methods
? REST API 是什么 – HTTP Status Codes

3、RESTful API是什么？

RESTful API就是REST API，術語 REST API 和 RESTful API 可以互換使用。

學習RESTful API時容易混淆的概念問題：

• RPC 和 RESTful API 區分不明，很容易把基于HTTP的RPC 風格認定為RESTful 風格。
• OpenAPI 和 RESTful API關系不明，很容易把滿足OpenAPI規范的API 等同于 RESTful API 。
• Web API 和 RESTful API是什么關系不明，在使用時會概念互換。
• 其它一些REST API概念常見問題清單。

4、理解"統一接口"原則

統一接口是一切 RESTful Web 服務設計的基礎。其表示服務器以標準格式傳輸信息。格式化的資源在 REST 中稱為表征。此格式可以與服務器應用程序上資源的內部表征不同。例如，服務器可以將數據存儲為文本，但以 JSON 表征格式發送該數據。

統一接口強制實施四個架構約束：

1. 請求應確定資源。它們通過使用統一的資源標識符實現此功能。
2. 客戶端包含資源表征中的足夠信息以修改或刪除資源（如需要）。服務器通過發送進一步描述資源的元數據以符合這一條件。
3. 客戶端接收有關如何進一步處理表征的信息。服務器通過發送自描述信息實現此功能，該信息包含了有關客戶端如何以最佳方式使用這些信息的元數據。
4. 客戶端接收有關其完成任務需要的所有其他相關資源的信息。服務器通過在表征中發送超鏈接實現此功能，以便客戶端可以動態發現更多資源。

二、理解REST資源概念

REST資源中信息的關鍵抽象是一個資源。我們可以命名的任何信息都可以成為一種資源。例如，REST資源可以是文檔或圖像、時間服務、其他資源的集合或非虛擬對象（例如一個人）。
在任何特定時間，資源的狀態都被稱為資源表示。資源表示包括：

• 數據
• 描述數據的元數據
• 以及可以幫助客戶端過渡到下一個所需狀態的超媒體鏈接。

REST API由一個相互鏈接的資源組成組成。這組資源被稱為REST API的資源模型。

1)資源標識符

REST使用資源標識符來識別客戶端和服務器組件之間交互中涉及的每個資源。

2)超媒體

表示的數據格式被稱為媒體類型。媒體類型標識了一個規范，該規范定義了如何處理表示。

RESTful API看起來像超文本。每個可尋址信息單元都攜帶一個地址，要么顯式（例如，鏈接和id屬性），要么隱式（例如，從媒體類型定義和表示結構派生）。

3)自我描述

此外，資源表示應是自我描述的：客戶不需要知道資源是員工還是設備。它應該根據與資源相關的媒體類型進行操作。
因此，在實踐中，我們將創建許多自定義媒體類型——通常與一個資源關聯的一種媒體類型。
每種媒體類型都定義了默認處理模型。例如，HTML定義了超文本的渲染過程和圍繞每個元素的瀏覽器行為。

三、如何描述RESTful API？

RESTful API是隨著互聯網SAAS業務的發展而興盛，post:開放API給更多的人使用是其核心目標之一，2011年由SmartBear Software的首席執行官Dann Milner提出OpenAPI描述，逐步發展為一套REST API描述規范（它類似SOAP的描述規范WSDL）。
Open API描述規范 為REST API on HTTP提供了一個正式的標準，它使用YAML或JSON格式，描述API的路徑、參數、請求和響應的結構、錯誤碼等信息。
JSON格式示意：

{

 "title": "Sample Pet Store App",

 "description": "This is a sample server for a pet store.",

 "termsOfService": "http://explinks.com/terms/",

 "contact": {

 "name": "API Support",

 "url": "http://m.dlbhg.com/support",

 "email": "support@example.com"

 },

 "license": {

 "name": "Apache 2.0",

 "url": "http://www.apache.org/licenses/LICENSE-2.0.html"

 },

 "version": "1.0.1"

}

YAML格式示意：

title: Sample Pet Store App

description: This is a sample server for a pet store.

termsOfService: http://explinks.com/terms/

contact:

 name: API Support

 url: http://m.dlbhg.com/support

 email: support@example.com

license:

 name: Apache 2.0

 url: http://www.apache.org/licenses/LICENSE-2.0.html

version: 1.0.1

由于 OpenAPI 描述是計算機可讀的，因此可以使用它來執行如下操作：

• 生成庫以方便使用 REST API
• 驗證并測試使用 REST API 的集成
• 使用第三方API設計工具（如 Postman）探索 REST API 并與之交互。

四、如何設計RESTful API？

RESTful API的架構約束理解起來很容易，設計起來靈活度很大，以下是一些主要設計原則：

• REST API是圍繞資源設計的，這些資源是客戶端可以訪問的任何類型的對象、數據或服務。
• 資源有一個標識符，這是一個唯一標識該資源的URI。例如，特定客戶訂單的URI可能是：https://adventure-works.com/orders/1
• 客戶通過交換資源表示與服務交互。許多Web API使用JSON作為交換格式。例如，對上面列出的URI的GET請求可能會返回此響應主體：{"orderId":1,"orderValue":99.90,"productId":1,"quantity":1}
• REST API使用統一的接口，這有助于將客戶端和服務實現解耦。對于基于HTTP構建的REST API，統一接口包括使用標準HTTP動詞對資源執行操作。最常見的操作是GET、POST、PUT、PATCH和DELETE。
• REST API使用無狀態請求模型。HTTP請求應該是獨立的，并且可以以任何順序發生，因此在請求之間保留瞬態狀態信息是不可行的。存儲信息的唯一地方是資源本身，每個請求都應該是一個原子操作。這種約束使網絡服務具有高度可擴展性，因為不需要在客戶端和特定服務器之間保留任何親和力。任何服務器都可以處理來自任何客戶端的任何請求。也就是說，其他因素可能會限制可擴展性。例如，許多Web服務寫入后端數據存儲，這可能很難擴展。
• REST API由表示中包含的超媒體鏈接驅動。例如，以下顯示了訂單的JSON表示。它包含獲取或更新與訂單關聯的客戶的鏈接。

但在具體操作中卻比較復雜，網上有大量的API設計指導及規范，我們搜集、整理了一部分：

RESTful API設計概要RESTful API 狀態碼設計指南RESTful API 設計檢查清單

五、如何評估RESTful API成熟度？

2008年，Leonard Richardson為Rest API提出了以下 RESTful成熟度模型：

• 級別0：定義一個URI，所有操作都是對此URI的POST請求。
• 第1級：為單個資源創建單獨的URI。
• 第2級：使用HTTP方法定義資源上的操作。
• 第3級：使用超媒體（HATEOAS，如下所述）。

根據Fielding的定義，第3級對應于一個真正的RESTful API。在實踐中，許多已發布的Web API大約在2級左右。

六、RESTful API的安全性

RESTful API的安全性 也始于行業最佳實踐，例如使用散列算法確保密碼安全性，使用 HTTPS 實現安全數據傳輸。 像 OAuth 2.0這樣的授權框架可以幫助限制第三方應用程序的特權。 使用 HTTP 頭中的時間戳記，API 還可以拒絕在特定時間段后到達的任何請求。 同時也可以通過參數驗證和 JSON Web 令牌等方式來確保只有經過授權的客戶端才能訪問 API。

參考資料：

架構風格與基于網絡應用軟件的架構設計（中文修訂版）
10大REST API常見問題？
https://restfulapi.net
https://aws.amazon.com/cn/what-is/restful-api/
什么是API？(Aws)
REST與SOAP的區別？
介紹 Web 基礎架構設計原則的經典論文《架構風格與基于網絡的軟件架構設計》導讀