[ADP-307] 啟發性 URI 設計集合

本文件收集了從各種公開 API 文件中觀察到的啟發性 URI 設計模式。這些設計模式雖然可能超出傳統 RESTful API 的路徑設計範疇，但其語意表達清晰，往往能減少額外的 Header 或 Request 設計需求。

注意：這些設計模式僅供參考，不一定適用於所有 API 設計場景。

URI 設計模式分類

1. 修飾詞模式

透過在路徑末端添加修飾詞，用以表達資源的特定狀態或範圍：

GET /users/{username}/events/public      # 獲取公開事件
GET /user/marketplace_purchases/stubbed   # 獲取測試用的購買資訊
POST /applications/{client_id}/token/scoped  # 創建有特定範圍的令牌

2. 識別符設計模式

使用具有語意的識別符，提升 URL 的可讀性：

GET /apps/{app_slug}  # 使用可讀的 slug 而非 UUID

3. 資源關係表達模式

清晰表達資源之間的關係和操作：

GET /enterprises/{enterprise}/actions/permissions/selected-actions
GET /user/starred/{owner}/{repo}  # 檢查認證用戶是否標星該倉庫
GET /orgs/{org}/installations    # 獲取組織的安裝項目

4. 特定操作模式

針對特定資源的專門操作：

POST /repos/{owner}/{repo}/merge-upstream  # 合併上游變更
POST /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins  # 強制管理員保護

5. 資源狀態查詢模式

用於查詢特定資源的狀態或關聯資料：

GET /users/self/requested-by     # Instagram: 查詢請求關注的用戶
GET /user/starred               # 獲取已標星的項目
GET /v3/groups/owned           # GitLab: 獲取用戶擁有的群組

6. 單例資源模式

用於表示在特定上下文中只存在一個實例的資源：

GET /user/profile              # 獲取當前用戶的個人資料
GET /system/configuration      # 獲取系統配置
GET /apis/{api-id}/stages/dev  # 獲取特定 API 的開發環境階段

歡迎貢獻更多 API 設計範例，豐富這個集合。

Changelog

• 2025.03.07: Fully rewrite this document