[ADP-301] 資源導向設計
reviewing phase 1
需要更多參考資料
概述
資源導向設計是 REST API 開發中的一個基本方法，它圍繞資源構建 API 結構，這些資源是 API 提供的資訊或服務的關鍵抽象。
指導原則
- API 設計者必須(MUST)識別並明確定義其 API 將暴露的資源。
- 資源應該(SHOULD)由唯一且邏輯的 URI 表示。
- API 實現必須(MUST)使用適當的 HTTP 方法(GET、POST、PUT、DELETE 等)來對資源執行操作。
TIP
請見 ADP-110: HTTP 方法。
- 資源表示應該(SHOULD)使用標準格式(包含JSON或XML)，本 API 設計原則規定使用 JSON。
- API 交互必須(MUST)是無狀態的，每個請求都包含所有必要的資訊。
TIP
長時間任務可以視作一個符合規範的例外，請見ADP-357: 長時間任務。
- API 設計者應該(SHOULD)在資源 URI 中使用名詞而非動詞。
TIP
當設計
POST+ 動作相關端點時，視作名詞，參考ADP-302: URL 設計原則。 - API 實現必須(MUST)實現正確的 HTTP 狀態碼。
- API 設計者應該(SHOULD)提供清晰一致的命名約定。
- 集合資源應該(SHOULD)使用複數名詞。
- API 實現必須(MUST)實現適當的錯誤處理和訊息傳遞。
- API 設計者可以(MAY)考慮對其 API 進行版本控制以管理隨時間的變化。
什麼是資源？
在 REST API 上下文中，資源是可以在網絡上被識別、命名、尋址或處理的任何命名資訊或服務。資源可以是單一實體(例如，特定用戶)或集合(例如，所有用戶)。它們是 REST API 操作的基本概念。
什麼不是資源導向的 API 設計？
為了更好地理解資源導向設計，認識不符合這一原則的方法會有所幫助：
以動作為中心的 API 設計：
- 示例：
/getUser、/createPost、/deleteComment - 這些設計在 URI 中包含了操作，而不是使用 HTTP 方法來表示動作。
- 示例：
RPC 風格的 API：
- 示例：
/api/doSomething、/api/processData - 這些設計更像是遠程過程調用，而不是對資源的操作。
- 示例：
單一端點 API：
- 示例：
/api(所有操作都通過這個單一端點執行，通過參數區分) - 這種設計缺乏明確的資源概念，將所有操作混在一起。
- 示例：
這些非資源導向的 API 設計通常會導致 API 更難理解、使用和維護，也不利於 API 的擴展和演進。
示例
考慮一個簡單的部落格 API：
資源：
- 貼文
- 評論
- 用戶
URI 設計：
- /posts(所有貼文的集合)
- /posts/{id}(特定貼文)
- /posts/{id}/comments(特定貼文的評論)
- /users(所有用戶的集合)
- /users/{id}(特定用戶)
HTTP 方法：
- GET /posts - 檢索所有貼文
- POST /posts - 創建新貼文
- PUT /posts/{id} - 更新特定貼文
- DELETE /posts/{id} - 刪除特定貼文