Documentation
Computer Science
System Design
API
RESTful API

RESTful API

RESTful API 是基於 REST（Representational State Transfer）架構風格設計的 API，使用 HTTP 方法對資源進行操作。

HTTP Methods

MethodIdempotentSafe用途
GETYesYes檢索資源
POSTNoNo建立新資源
PUTYesYes完整更新資源
PATCHNoNo部分更新資源
DELETEYesYes刪除資源

GET

GET 方法用於從伺服器檢索資源。可以說是安全的方法，因為它不會以任何方式改變資源的狀態。
  • Idempotent: Safe
  • 用於讀取資料，不應產生副作用

POST

POST 用於在伺服器上的資源集合中建立新資源。
  • Non-Idempotent: Not Safe
  • 每次呼叫可能產生不同結果（如建立新記錄）

PUT

PUT 用於更新伺服器上的現有資源，並且更新完整資源。
  • Idempotent: Safe
  • 完整取代目標資源

PATCH

PATCH 用於更新伺服器上現有的資源，它更新資源的一部分。
  • Non-Idempotent: Not Safe
  • 部分更新資源欄位

DELETE

DELETE 用於從伺服器刪除資源，它刪除由 Request-URI 標識的資源。
  • Idempotent: Safe
  • 刪除指定資源

PATCH vs PUT

PUT 方法主要完全取代整個現有資源，但 PATCH 部分更新現有資源。
特性PUTPATCH
更新範圍完整資源部分欄位
請求內容完整資源表示僅變更的欄位
冪等性YesNo

Idempotence（冪等性）

是指同樣的請求被執行一次與連續執行多次的效果是一樣的，伺服器的狀態也是一樣的。換句話說，冪等方法不應該有副作用（統計用途除外）。

冪等性範例 

# GET - 冪等
GET /users/123  → 無論執行幾次，結果相同

# DELETE - 冪等
DELETE /users/123  → 第一次刪除成功，之後回傳 404，但伺服器狀態相同

# POST - 非冪等
POST /users  → 每次執行都建立新使用者

RESTful 設計原則

  1. 資源導向: URL 代表資源，而非動作
  2. 使用 HTTP 方法: 動作由 HTTP method 表達
  3. 無狀態: 每個請求包含所有必要資訊
  4. 統一介面: 一致的 URL 結構和回應格式

URL 設計範例

操作HTTP MethodURL
取得所有使用者GET/users
取得單一使用者GET/users/{id}
建立使用者POST/users
更新使用者PUT/PATCH/users/{id}
刪除使用者DELETE/users/{id}
Password StorageWebhooks