iT邦幫忙

2025 iThome 鐵人賽

DAY 10
0
佛心分享-IT 人自學之術

API 實戰入門從設計到驗證系列 第 10

Day10 API 資源與資源導向設計

  • 分享至 

  • xImage
  •  

在API的設計裡,「資源」是最核心的概念之一。資源可以理解為系統中的資料或功能單位,例如使用者、訂單、商品、文章等,每個資源通常會對應到一個端點(Endpoint),而不同的HTTP方法則決定了如何操作這些資源。

資源導向設計的思維,強調用清楚的結構來呈現系統功能。例如:

  • /users:代表所有使用者。
  • /users/123:代表編號123的使用者。
  • /users/123/orders:代表編號123使用者的訂單。

這種設計方式能讓API更有一致性和可讀性,開發者一看端點就能明白對應的資料與功能。

資源的設計還需要考慮層次關係與命名規則,層次關係反映出資料的從屬,例如「使用者」底下可能有「訂單」,而訂單底下可能有「商品」,命名則應該清楚、簡短、使用複數名詞,如 /orders,比起模糊或過於技術性的名稱更直覺。

除了結構與命名,還要重視資源狀態的表達方式。每個資源都應該有清楚的屬性與資料格式,例如使用JSON時,欄位名稱必須保持一致,避免混淆或增加理解成本,API回應中也能提供導覽資訊,例如在查詢某個使用者時,同時附上該使用者訂單的連結,讓開發者能順著資源關係繼續操作。

另一個重要原則是「統一的操作方式」,在RESTful設計裡,透過標準的HTTP方法來對資源進行操作:

  • GET /users/123:取得使用者資訊。
  • POST /users:新增一個使用者。
  • PUT /users/123:更新使用者資訊。
  • DELETE /users/123:刪除指定使用者。

統一的規範讓使用者只要理解資源的結構與方法,就能快速上手API。


上一篇
Day9 API 資料格式與一致性
系列文
API 實戰入門從設計到驗證10
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言