ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-300] REST 概述 ​

reviewing phase 1

連結所有 ADP

INFO

本 ADP 提供了 REST（表述性狀態轉移）原則和 API 設計最佳實踐的概述。

ADP 編號範圍：300-349

我們對 REST 的實用方法 ​

我們採用實用型 RESTful（Pragmatic RESTful）方法，而非嚴格遵循 Roy T. Fielding 的原始 REST 定義或完全遵照 Richardson 成熟度模型（RMM）。這種實用方法：

  • 注重實際實現需求，而非學術純粹性
  • 不盲目追求 HATEOAS（超媒體作為應用狀態引擎）當它增加不必要的複雜性
  • 透過利用現有和新興的 HTTP RFC 能力來擴展 RMM 描述不足的部分
  • 優先考慮開發者體驗和 API 可用性

這種實用的立場使我們能夠創建在精神上符合 RESTful 且在實現上實用的 API，平衡理論正確性與現實世界需求。

關鍵概念 ​

資源 (Resource) ​

REST 以資源為中心，資源是系統中可以識別、命名、定址或處理的任何實體。資源通常是名詞，應使用清晰、描述性的術語命名。

表述 (Representation) ​

資源可以有多種表述形式，如 JSON、XML 或 HTML。表述格式通常使用 Content-Type 標頭指定。

HTTP 方法 ​

RESTful API 使用標準 HTTP 方法對資源進行操作：

  • GET：檢索資源
  • POST：創建新資源
  • PUT：更新(並取代)現有資源
  • DELETE：刪除資源
  • PATCH：部分修改資源

關於 HTTP 方法，請見 ADP-110: HTTP 方法。

無狀態 ​

客戶端向伺服器的每個請求必須包含理解和處理該請求所需的所有資訊。伺服器不應在請求之間存儲任何客戶端上下文。

最佳實踐 ​

設計 RESTful API 時：

  • 在端點路徑中使用名詞而非動詞
  • 為保持一致性使用複數名詞（例如，使用 /users 而非 /user）
  • 適當使用 HTTP 方法進行 CRUD 操作
  • 使用適當的 HTTP 狀態碼表示請求結果
  • 實施適當的錯誤處理並提供有意義的錯誤訊息
  • 使用查詢參數進行過濾、排序和分頁
  • 對 API 進行版本控制以保持向後兼容性

以上內容在下列各 ADP 內會詳細描述。

相關 ADP ​

參考資料 ​