REST規範介紹

REST（Representational State Transfer）即表現層狀態轉移，是一種軟件架構風格，定義了一組架構約束條件和原則，常用於Web服務器和客戶端之間的通訊。REST通訊採用無狀態的請求響應式通訊方式，可以使服務端的負載和可擴展性得到很大的提高。

一、REST規範請求方法

REST請求代表特定的HTTP方法（GET、POST、PUT、DELETE），如發送一個GET請求代表獲取一個資源，發送一個POST請求代表創建一個新的資源。HTTP協議中定義了一組簡單的操作，即HTTP方法，用來指明用戶希望對指定的資源執行什麼樣的操作，包括以下常用的四種：

• GET： 用於獲取資源。如果請求成功，則返回表示資源的實體，否則返回錯誤碼。GET請求不應該有副作用。
• POST： 用於創建資源。請求成功後會返回資源的實體。POST請求應該有副作用，如修改存儲內容。
• PUT： 用於更新資源。如果請求成功，則返回更新後的資源。PUT請求也應該有副作用。
• DELETE： 用於刪除資源。如果請求成功，則返回刪除的實體。DELETE請求也應該有副作用。

下面是一個基於REST風格的API的示例：

GET /users        // 獲取所有用戶
POST /users       // 創建一個新用戶
PUT /users/123    // 更新編號為123的用戶
DELETE /users/123 // 刪除編號為123的用戶

二、REST接口規範

REST接口規範有以下幾個方面：

1.資源標識符（URI）

每一個資源都有一個唯一的URI標識符，表示該資源。URI由主機名、端口號、資源路徑構成。URI由三部分構成，即：scheme://host:port/path?query_string。其中scheme代表請求協議（http、https等），host代表主機名、port代表端口號，path代表資源路徑。

2.HTTP方法

REST風格的API使用HTTP協議中的方法來表示對資源的操作。常用的方法是GET、POST、PUT和DELETE方法。

3.消息負載格式

REST風格的API消息負載一般使用JSON格式，XML格式也是一種常用的消息負載格式。這種格式可以很好地表達資源的屬性。

4.自描述消息

自描述消息是指消息本身包含足夠的信息，從而使接受者能夠理解消息的內容。這種消息清晰明了，無需外界解釋就能被解析。

三、RESTful規範

RESTful規範是一種滿足REST架構風格的API設計約束條件和規範，可以提供簡單、可擴展、易於維護和易於升級的API設計方式。以下是RESTful規範的幾個關鍵方面：

1.資源

任何可訪問的對象都是資源，如用戶、公司等。每個資源都具有自己的資源標識符，可以使用HTTP請求訪問。

2.表現層

資源的表現層是指以某種表現形式呈現給客戶端的內容，如JSON、XML等。資源的表現形式不受資源本身的狀態影響。

3.狀態轉移

客戶端通過向服務器發送請求並解析服務器的響應來以域模型為中心處理資源。資源上的狀態可以通過HTTP方法來操作，如GET、POST、PUT、DELETE等。

四、REST接口

使用REST風格的API設計，需要注意以下事項：

1.資源的選擇和命名

在設計RESTful API時，需要明確使用哪些資源標識符，以及如何命名它們。資源命名必須清晰、明確，並且易於理解和使用，以提高API的可用性和易用性。

2.合適的HTTP方法

在使用HTTP方法時，需要選擇正確的方法，以便正確地表示資源上的操作。在使用GET方法時，應當對資源進行瀏覽、查找或檢索。在創建資源時，應使用POST方法。在更新指定資源時，應使用PUT方法；如果只更新資源的一部分，則應使用PATCH方法。

3.狀態碼

HTTP狀態碼是RESTful API的一個重要組成部分，可以用來表示請求的成功和失敗。常見的狀態碼有200（請求已成功，請求的數據包含在響應中）、201（成功請求並創建了新資源）、204（請求已成功，但沒有返回數據）、400（客戶端請求語法錯誤）、404（請求的資源不存在）、500（服務器內部錯誤）等。

4.副作用

RESTful API請求和響應應儘可能避免副作用。例如，在執行PUT請求時，不能產生新的資源或改變服務器狀態。這些請求應該只是對現有資源進行更新。

代碼示例

獲取用戶列表

GET /users

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 1,
      "name": "Alice",
      "age": 22
    },
    {
      "id": 2,
      "name": "Bob",
      "age": 24
    }
  ]
}

創建一個新用戶

POST /users

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 3,
  "name": "Charlie",
  "age": 28
}

更新一個已有用戶

PUT /users/1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "Alice",
  "age": 24
}

刪除一個用戶

DELETE /users/2

HTTP/1.1 204 No Content