[ADP-49] API 術語註冊
reviewing phase 1
- 這篇文章尚未產生一個內部連結用以置放註冊頁面。
- 這篇規範尚未定義如何更新註冊。
概述
本文試圖建立一個 API 術語註冊流程，以確保整個組織內 API 相關術語的一致性和標準化。該流程受到 IANA 註冊程序的啟發，並根據我們組織的具體情況進行了調整。
標準詳情
問題類型註冊
- 定義：用於註冊 API 錯誤回應中使用的新問題類型的流程。
- 文件必須(MUST)包括：
- 問題類型標識符
- 描述
- 必需屬性
- 可選屬性
- 使用示例
HTTP 自定義偏好註冊
- 定義：用於註冊 API 請求中使用的自定義 HTTP 偏好的流程。
- 文件必須(MUST)包括：
- 偏好名稱
- 描述
- 語法
- 預期用途
應用程序 ID 註冊（URN 或自定義 MIME 類型）
- 定義：用於註冊唯一應用程序標識符的流程，可以是 URN 或自定義 MIME 類型。
- 文件必須(MUST)包括：
- 應用程序 ID（URN 或 MIME 類型）
- 應用程序描述
- 版本資訊（如適用）
- 使用指南
自定義標頭註冊
- 定義：用於註冊 API 請求和回應中使用的自定義 HTTP 標頭的流程。
- 文件必須(MUST)包括：
- 標頭名稱
- 描述
- 語法
- 適用範圍（請求、回應或兩者）
- 使用指南
鏈接關係註冊
- 定義：用於註冊 API 回應中使用的鏈接關係類型的流程。
- 註冊流程必須(MUST)包括：
- 提交帶有理由說明的提案
- 審核是否與現有標準存在潛在衝突
- 批准並記錄
- 文件必須(MUST)包括：
- 關係名稱
- 描述
- 參考
- 使用指南
授權方案註冊
- 定義：用於註冊 API 安全中使用的授權方案的流程。
- 文件必須(MUST)包括：
- 方案名稱
- 描述
- 令牌格式（如適用）
- 標頭格式
- 必需的聲明或參數
- 可選的聲明或參數
- 使用指南
- 安全考慮
術語維護和可訪問性
- 組織必須(MUST)維護一個中央存儲庫，用於存儲所有註冊的術語、問題類型、偏好和應用程序 ID 等。
- 組織必須(MUST)實施定期審核流程，以確保所有註冊項目保持相關性和最新狀態。
- 組織必須(MUST)提供搜索和瀏覽功能，以便輕鬆訪問註冊項目。
合規性
- 所有 API 設計和實現必須 (MUST) 在適用的情況下使用註冊的術語、問題類型、偏好和應用程序 ID 等。
責任
- API 治理團隊應 (SHOULD) 監督註冊流程、審核提交內容並維護註冊表。
- API 設計師和開發人員應 (SHOULD) 提交新項目進行註冊，並且必須 (MUST) 在其工作中使用註冊項目。
- 文件團隊應 (SHOULD) 確保在 API 文件中一致使用註冊項目。
相關 ADPs
註冊示例
問題類型註冊表
| 問題類型 | 描述 | 必需屬性 | 可選屬性 | 使用示例 |
|---|---|---|---|---|
| https://api.example.com/problems/resource-not-found | 表示請求的資源不存在 | detail, instance | title | {"type": "https://api.example.com/problems/resource-not-found", "title": "資源未找到", "detail": "請求的用戶 ID 12345 不存在", "instance": "/users/12345"} |
| https://api.example.com/problems/invalid-input | 表示提供的輸入無效 | detail, errors | title, instance | {"type": "https://api.example.com/problems/invalid-input", "title": "無效輸入", "detail": "提供的數據未通過驗證", "errors": [{"field": "email", "message": "無效的電子郵件格式"}]} |
HTTP 自定義偏好註冊表
| 偏好名稱 | 描述 | 語法 | 預期用途 |
|---|---|---|---|
| example-api-version | 指定所需的 API 版本 | example-api-version=YYYY-MM-DD | 允許客戶端請求特定的 API 版本 |
| example-response-format | 指定所需的回應格式 | example-response-format=(json|xml) | 允許客戶端請求特定的回應格式 |
應用程序 URN ID 註冊表
| 應用程序 ID | 描述 | 版本 | 使用指南 |
|---|---|---|---|
| urn:example:app:inventory-management | 庫存管理應用程序 | 1.0 | 在 API 請求和回應中使用此 URN 來識別庫存管理應用程序 |
自定義 MIME type 註冊表
| MIME type | 描述 | 版本 | 使用指南 |
|---|---|---|---|
| application/vnd.example.user-profile+v1.json | 用戶配置文件數據的自定義 MIME 類型 | v1 | 在發送或接收 JSON 格式的用戶配置文件數據時使用此 MIME 類型 |
自定義標頭註冊表
| 標頭名稱 | 描述 | 語法 | 適用範圍 | 使用指南 |
|---|---|---|---|---|
| X-API-Key | 用於 API 認證 | X-API-Key: <api_key> | 請求 | 在所有 API 請求中包含此標頭以進行認證 |
| X-Rate-Limit-Remaining | 指示當前速率限制窗口中剩餘的請求數 | X-Rate-Limit-Remaining: <integer> | 回應 | 檢查 API 回應中的此標頭以管理請求速率並避免超過限制 |
| X-Request-ID | 請求的唯一標識符，用於跟踪和調試 | X-Request-ID: <uuid> | 兩者 | 為每個請求生成唯一 ID，並在請求和回應標頭中包含它以進行跟踪 |
鏈接關係註冊表
| 關係名稱 | 描述 | 參考 | 使用指南 |
|---|---|---|---|
| next | 表示鏈接的上下文是系列的一部分，而系列中的下一個是鏈接目標 | [RFC5988] | 在分頁中使用，鏈接到結果的下一頁 |
| self | 傳達鏈接上下文的標識符 | [RFC5988] | 用於提供資源的規範 URL |
授權方案註冊表
| 方案名稱 | 描述 | 令牌格式 | 標頭格式 | 必需的聲明/參數 | 可選的聲明/參數 | 使用指南 | 安全考慮 |
|---|---|---|---|---|---|---|---|
| Bearer Token | 一種簡單的基於令牌的認證方案 | JWT | Authorization: Bearer <token> | iss, sub, exp | aud, nbf, iat | 用於大多數 API 認證場景 | 確保令牌通過 HTTPS 傳輸；驗證所有聲明 |
| customschema Token | 一種簡單的基於令牌的認證方案 | JWT | Authorization: customschema <token> | iss, sub, exp | aud, nbf, iat | 用於大多數 API 認證場景 | 確保令牌通過 HTTPS 傳輸；驗證所有聲明 |