了解 REST API - 不耐煩者指南

我的文章在這裡交叉發布

REST（Re示範 State T傳輸）API 是現代 Web 開發的支柱。本文將詳細介紹如何建立和使用現代 REST API、製作 API 時要考慮哪些設計決策以及作為 REST 基礎的理論。

實用指南

本節深入探討如何將 REST API 與 HTTP 結合使用，涵蓋端點、方法、請求和回應。您將找到開始進行 API 呼叫和在專案中應用 REST 所需的一切。

如何建構 URI

一般來說，處理 URI 有兩種主要方法：

1. 作為動作
2. 作為資源

考慮以下兩個 URI：

1. https://example.com/getUserData?id=1（操作）
2. https://example.com/users/1（資源）

兩個範例都顯示我們檢索 id 為 1 的使用者的使用者資料。差別在於，在第一個範例中，路由 /getUserData 正在執行操作，而在第二個範例中，路由 /users/1 是資產，它並沒有表示正在執行什麼操作。我們可以說這種類型的 URI 充當名詞（因為它是一個事物而不是一個動作，即動詞）。

REST 模式要求我們嚴格使用 URI，如第二個範例。我們希望我們的 URI 是名詞，這樣我們就可以使用 HTTP 方法作為動詞來對這些名詞執行操作。例如，我們可以使用 HTTP 方法 GET 檢索有關 /users/1 的信息，但我們可以使用 PUT 更新相應用戶的信息，或使用 DELETE 完全刪除用戶。

關於 URI 需要注意的最後一件事是，與上面的範例一樣，當引用單一資源（例如本例中的單一使用者）時，URI 應以該資源的唯一識別碼結尾。引用給定類別中的所有資源時，應省略唯一識別碼。

1. https://example.com/users/1 - 引用 id 為 1 的特定用戶
2. https://example.com/users - 引用所有用戶，無論 id 為何

支持哪些行動

REST 支援4 個主要操作，我們使用縮寫CRUD 來記住它們：Create、Read、U 更新，D刪除。這些操作中的每一個都對應到一個我們可以用來執行該操作的 HTTP 方法。映射如下：

Action	HTTP Method
Create	POST
Read	GET
Update	PUT / PATCH
Delete	DELETE

支援的所有操作 URI 組合

每個 REST API 其實只是（至少）5-6 個路由。在我們的範例中，基本端點將是 /users，我們將假裝將其託管在 https://example.com 上。

• 取得 https://example.com/users
  • Action：傳回所有使用者資產（每個資產為一個使用者）
  • 請求正文：空
  • 回應正文：使用者資產清單（作為 JSON 陣列）
• GET https://example.com/users/[id] （[id] 是變數）
  • 操作：僅傳回單一請求的使用者資產
  • 請求正文：空
  • 回應正文：僅具有符合ID的使用者資產（作為JSON）
• 發佈 https://example.com/users
  • 操作：將一項使用者資產加入集合
  • 請求正文：建立新使用者資產所需的所有資料（不需要特定格式，建議使用JSON）
  • 回應正文：插入唯一 ID （作為 JSON） 的新建立的資產
• PUT https://example.com/users/[id] （[id] 是變數）
  • 操作：用給定資料完全取代一個現有使用者的資料
  • 請求正文：取代現有使用者資料所需的所有數據，無論是否已更改（減去 id - 不需要特定格式，建議 JSON）
  • 回應正文：具有匹配ID 的新更新資產（作為JSON）
• （可選） PATCH https://example.com/users/[id] （[id] 是變數）
  • 操作：用給定資料部分取代一個現有使用者的資料
  • Request Body：只需要更新的資料（減 id - 不需要特定格式，建議 JSON）
  • 回應正文：具有匹配ID 的新更新資產（作為JSON）
• 刪除 https://example.com/users/[id] （[id] 是變數）
  • 操作：僅從使用者表中刪除一筆記錄
  • 請求正文：無
  • 回應正文：無（僅 HTTP 回應代碼）或剛刪除的具有匹配 ID 的資產中的資料（作為 JSON）

設計考慮因素

除了定義端點是否使用 REST 模式之外，在開始建立端點之前還有很多事情需要考慮。您將來是否有可能想要更新您的端點？您的輸出是否應該向使用者提供有用的提示？ REST 是否適合您的情況使用？讓我們回答其中一些問題。

對您的端點進行版本控制

從一開始就開始考慮 API 的版本控制可能是個好主意，以便將來更容易進行更改。有幾種不同的方法可以確定使用者選擇使用的 API 版本：

• URI 版本控制
  • 版本號碼被合併到 URL 路徑中，通常位於底部
  • 範例：
  • https://example.com/v1/users/1
  • https://example.com/v2/users/1
• 查詢參數
  • 版本號碼作為查詢參數附加在 API 端點
  • 範例：
  • https://example.com/users/1?apiVersion=1
  • https://example.com/users/1?apiVersion=2
• 基於標題
  • 版本號碼是一個特定且唯一的標頭欄位
  • 範例（請求標頭）：
  • x-api-版本：1
  • x-api-版本：2
• 內容協商
  • 版本是根據表徵狀態或媒體類型決定的。
  • 在下面的範例中，伺服器程式碼會知道firstName是第一個版本的名稱，並且在下一個版本中它被更改為givenName。
  • 範例（請求正文）：
  • { 名字: '亨利' }
  • {給定名稱：'亨利'}

模擬快速 REST API

有時，嘗試一下是了解它們如何運作的最佳工具。我最喜歡的演示 REST 的庫之一是 json-server。設定非常簡單 - 只需幾個步驟。

安裝 JSON 伺服器

npm install json-server

建立一個簡單的資料儲存

{
  "users": [
    { "id": "1", "username": "gorwell", "email": "gorwell@gmail.com" },
    { "id": "2", "username": "cdickens", "email": "cdickens@gmail.com" },
    { "id": "3", "username": "jausten", "email": "jausten@gmail.com" },
    { "id": "4", "username": "vwoolf", "email": "vwoolf@gmail.com" },
    { "id": "5", "username": "sking", "email": "sking@gmail.com" }
  ]
}

啟動伺服器

npx json-server db.json

向本機伺服器發出 HTTP 請求

curl -X GET http://localhost:3000/users/1

簡單的 CRUD 資料網格

功能齊全的 REST 端點可以使用 ZingGrid 輕鬆連接到資料網格，只需將基本 REST URI 指向 即可。元素的 src 屬性如下

<zing-grid src="http://localhost:3000/users" editor-controls></zing-grid>

最後的想法

REST API 在網路上有多種形狀和大小，每種都是為了滿足特定需求而客製化的。透過深思熟慮地建構 URI、選擇正確的操作並牢記版本控制，您可以創建一個簡單、靈活的 API，開發人員會樂於使用它。透過這些基本步驟，即使是快速原型也可以演變成健壯、可靠、經得起時間考驗的 API。

以上是了解 REST API - 不耐煩者指南的詳細內容。更多資訊請關注PHP中文網其他相關文章！