[ADP-110] HTTP 方法
概述
HTTP 方法，也稱為 HTTP 動詞，定義了在發出 HTTP 請求時要對資源執行的所需操作。
核心 HTTP 方法
以下 HTTP 方法是 RESTful API 設計的基礎:
GET
- 用於檢索資源或資源集合。
- 應該是冪等和安全的(無副作用)。
- GET 方法的詳細指南
POST
- 用於創建新資源或提交數據進行處理。
- 非冪等，因為多個相同的請求可能會導致多個資源創建。
- POST 方法的詳細指南
- 可以被設計為冪等，請參考 ADP-366: 冪等性支持
PUT
- 用於通過完全替換來更新現有資源。
- 應該是冪等的。
- PUT 方法的詳細指南
DELETE
- 用於刪除資源。
- 應該是冪等的。
- DELETE 方法的詳細指南
PATCH
- 用於部分修改現有資源。
- 可能是冪等的，也可能不是，取決於實現。
- PATCH 方法的詳細指南
- 可以被設計為冪等，請參考 ADP-366: 冪等性支持
其他 HTTP 方法
雖然不太常見，但這些方法在特定場景中可能有用:
HEAD
- 類似於 GET，但只檢索標頭，不檢索主體。
- 用於檢查資源元數據或存在性，而無需傳輸整個資源。
OPTIONS
- 用於描述目標資源的通信選項。
- 對 CORS 預檢請求和 API 發現有幫助。
指導原則
設計 API 時，請考慮以下原則:
- 應該支持冪等性
- 為每個操作使用適當的 HTTP 方法以保持語義一致性。
- 確保 GET 請求始終是安全的，不會修改伺服器狀態。
- 對於完整的資源更新，優先使用 PUT 而不是 PATCH，以維持冪等性。
- 對於非冪等操作或當伺服器決定資源標識符時使用 POST。
- 為每種方法實現適當的錯誤處理和狀態代碼。
方法安全性和冪等性
- 安全方法(GET、HEAD、OPTIONS)不應修改資源。
- 冪等方法(GET、PUT、DELETE、HEAD、OPTIONS)多次調用應產生相同結果。
API 設計考慮因素
- 一致性:在整個 API 中一致地使用 HTTP 方法。
- 可緩存性:利用緩存標頭，特別是對於 GET 請求。
- 無狀態:設計您的 API 為無狀態，每個請求包含所有必要資訊。
- 資源命名:使用清晰、層次化的資源命名約定。
常見陷阱
- 使用 GET 請求修改伺服器狀態。
- 實現非冪等的 PUT 請求。
- 過度使用 POST 進行所有操作，而不是使用適當的方法。
- 忽視 PUT 和 PATCH 之間的語義差異。
實現示例
以下是在 RESTful API 中如何為用戶資源使用不同 HTTP 方法的簡單示例:
http
GET /users # 檢索用戶列表
GET /users/{id} # 檢索特定用戶
POST /users # 創建新用戶
PUT /users/{id} # 更新用戶(完全替換)
PATCH /users/{id} # 部分更新用戶
DELETE /users/{id} # 刪除用戶