[ADP-306] URI 設計模式
概述
為 API 設計路徑是一件不算有完全正確答案且容易產生設計分歧的工作。本規範內容嘗試提供一些觀察到的設計模式，其內容可能會隨時間改進。我們鼓勵開發人員分享他們遇到的有效 URI 設計範例（請參閱 ADP-307 )，以幫助完善這些指導方針。
指導原則
應該(SHOULD)使用小寫字母作為 URI 路徑。
應該(SHOULD)使用連字符（-）分隔 URI 路徑中的單詞（即使用 kebab-case)。
必須(MUST)使用正斜杠（/）表示層次關係。
應該(SHOULD)在保持清晰的同時盡可能縮短 URI。
不得(MUST NOT)在 URI 中包含文件擴展名（例如 .json、.xml）。
應該(SHOULD)使用查詢參數(query parameters)進行過濾、排序和分頁。
必須(MUST)根據 RFC 3986 對 URI 中的特殊字符進行編碼。
不得(MUST NOT)以尾部斜杠 (/) 結束 URI。
INFO
由於 URI 路徑中的最後一個字符不會增加語義價值，並可能造成混淆，因此 URI 不得以尾部斜杠 (/) 結束。
正確做法
raw/customers/{user-id}/addresses/{address-id}錯誤做法
raw/customers/{user-id}/addresses/{address-id}/應該(SHOULD)參考下文提及的路徑模式進行設計。
如果需要，可(MAY)在 URI 中包含 API 版本（例如，
/v1/users)。參見ADP-41: API 版本控制。
路徑設計模式
模式 1：基於集合
集合的基本 URI：
/{resources}示例：
GET /users HTTP/1.1模式 1.1：集合中的單一特定資源
訪問集合中特定資源的 URI：
/{resources}/{resource-id}示例：
GET /users/12345 HTTP/1.1模式 1.1B：集合中的單一特定資源，無 ID 欄位
在某些情況下，需要訪問沒有傳統 id 標識符的資源。在這種情況下，我們必須確定一個唯一屬性(property)，如 name 或 type，以包含在 URI 中作為參考。
訪問無 ID 資源的 URI：
/{resources}/{resource-type|resource-name}示例：
GET /apis/{api-id}/stages/dev HTTP/1.1此示例演示了訪問由 {api-id} 標識的 API 的特定階段（dev），其中階段沒有傳統的 id，但可以通過其 name 唯一標識。
無 ID 資源的指導原則
- 唯一欄位識別：確保所選欄位（例如
name或type）在使用的上下文中是唯一的。 - 一致性：在類似類型的資源中一致使用相同的唯一欄位，以避免混淆。
- 清晰性：所選欄位應清楚地傳達它所代表的資源，使 URI 易於理解。
模式 1.2：嵌套資源
訪問嵌套資源的 URI：
/{resources}/{resource-id}/{nested-resources}/{nested-resource-id}示例：
GET /users/12345/orders/67890 HTTP/1.1模式 2：基於動作(action)
在 RESTful API 設計中，HTTP POST 通常代表 CREATE。然而，許多動作並不完全符合標準的 CRUD 操作。為了解決這個問題，可以使用動名詞來表示動作，同時保持 URI 不應包含動詞的原則。這些 URI 應該始終使用 POST 作為 HTTP 方法。
示例動作 URI：
POST /search
POST /users/login
POST /documents/12345/publishTIP
不應(SHOULD NOT)將 HTTP 方法置於路徑，如 POST /documents/delete
模式 3：帶修飾符的資源
修飾符可用於過濾或排序集合。這種模式應該是直觀和自解釋的。
帶修飾符的基本 URI：
/{resources}/{modifier}示例：
GET /songs/recently-played HTTP/1.1
GET /articles/top-rated HTTP/1.1