RESTful WebApi 設計概念

2022-12-17 2024-03-03 約 626 字預計閱讀 2 分鐘

本文為以下書籍的閱讀筆記，整理與紀錄一些我認為重要的部分

Web Api 設計

資源是 URL 的一部分，例如 /users
每一個資源通常有兩種路由，分別代表單數與複數資料
- 複數：GET http://{domain}/api/users
- 單數：GET http://{domain}/api/users/{userid}
使用資源名詞而非動詞
- 行為：取得使用者資料
  - 建議： GET {domain}/api/users/{userid}
  - 不建議： GET {domain}/api/getUserInfo/{userid}

利用 HTTP 方法表示功能行為

HTTP 方法	URL: /users	URL: /users/{userid}
Get	取得所有使用者資料	取得指定 user id 的資料
POST	建立一位使用者 (資料以 Request Body 傳遞)	不適用
PUT	批次更新使用者 (資料以 Request Body 傳遞、資料必須為完整的 User 資料)	指定更新 user id 的資料
PATCH	批次更新使用者 (資料以 Request Body 傳遞、資料為部分的 User 資料)	指定更新 user id 的資料
DELETE	刪除所有使用者	刪除指定使用者

URL 的路徑要可以表達每個資源的關係

1
2
3
4
5
GET {domain}/users/{userid}/name
取得          某個使用者id   的名稱

GET {domain}/unit/{unitid}/name
取得          某個單位id   的名稱

以 HTTP 行為表示與資料的互動關係，以後續的資源欄位表示要進行的行為

HTTP 方法	對應行為
POST	驗證、比較等無更新資料的行為
PUT	URL 即代表行為
PATCH	依據 query string 或是 request body 內的資料決定行為結果

範例

預期行為	HTTP 方法	URL	備註
驗證使用者資料資料	POST	{domain}/users/verify	驗證資訊會放置於 Http Request Body
調整使用者狀態為有效或無效 (範例1)	PATCH	{domain}/users/{userid}/status?invalid=true	使用 query string 設定狀態
調整使用者狀態為有效或無效 (範例2)	PATCH	{domain}/users/{userid}/status	使用 HttpBody 設定狀態: Body Context = {“invalid”=true}
設定使用者為無效使用者	PUT	{domain}/users/{userid}/status/invalid
設定使用者為有效使用者	PUT	{domain}/users/{userid}/status/valid