在API的設計裡,「資源」是最核心的概念之一。資源可以理解為系統中的資料或功能單位,例如使用者、訂單、商品、文章等,每個資源通常會對應到一個端點(Endpoint),而不同的HTTP方法則決定了如何操作這些資源。
資源導向設計的思維,強調用清楚的結構來呈現系統功能。例如:
這種設計方式能讓API更有一致性和可讀性,開發者一看端點就能明白對應的資料與功能。
資源的設計還需要考慮層次關係與命名規則,層次關係反映出資料的從屬,例如「使用者」底下可能有「訂單」,而訂單底下可能有「商品」,命名則應該清楚、簡短、使用複數名詞,如 /orders
,比起模糊或過於技術性的名稱更直覺。
除了結構與命名,還要重視資源狀態的表達方式。每個資源都應該有清楚的屬性與資料格式,例如使用JSON時,欄位名稱必須保持一致,避免混淆或增加理解成本,API回應中也能提供導覽資訊,例如在查詢某個使用者時,同時附上該使用者訂單的連結,讓開發者能順著資源關係繼續操作。
另一個重要原則是「統一的操作方式」,在RESTful設計裡,透過標準的HTTP方法來對資源進行操作:
/users/123
:取得使用者資訊。/users
:新增一個使用者。/users/123
:更新使用者資訊。/users/123
:刪除指定使用者。統一的規範讓使用者只要理解資源的結構與方法,就能快速上手API。