什麼是管理 API？
管理 API 的定義可能因使用的軟體或服務而異。在身份與存取管理 (IAM) 的背景下，管理 API 通常是指一組可以程式化管理 IAM 相關資源的 API。例如，使用者、應用程式、角色、權限、組織等。
儘管名稱未明確指定具體實現，但管理 API 通常是 RESTful 的，因為它能精確定義可在資源上執行的操作。因此，當你看到 POST /users 時，你可以預期這個 API 調用會創建一個新使用者。
為什麼管理 API 很重要？
管理 API 在 IAM 系統上創建了一個單獨的抽象層，但位於使用者介面下方。這使開發人員能夠自動化 IAM 資源的管理，這在多種情境下尤其有用：
1. 自動化
如其名所示，管理 API 允許你使用程式碼來管理資源，而不是通過使用者介面手動點擊。這在你需要管理大量使用者、應用程式或角色時特別有用。例如，你可以編寫腳本從 CSV 文件匯入使用者，並為他們分配正確的角色和權限。
2. 整合
管理 API 為服務對服務（或機器對機器 (machine-to-machine)）通信創建了一種標準方式。當你擁有多個需要與 IAM 系統通信的服務時，與其為每個服務實現自訂整合，不如設計一個良好的管理 API，通過 API 調用可適用於所有服務。例如，一個需要列出特定角色下所有使用者的服務，可以通過調用 GET /roles/{role_id}/users 來實現。
3. 組合和功能擴展
由於業務需求的多樣性，IAM 系統可能無法提供所有你需要的精確功能，特別是當涉及複雜的訪問控制 (access control) 要求時。管理 API 允許你在現有 IAM 系統之上構建自訂功能，而無需修改基礎平台或架構。
讓我們看一個日常例子：終端使用者需要更改他們的電子郵件地址。不同的應用程序可能有不同的要求：
- 應用程序 A 要求使用者驗證舊的和新的電子郵件地址。
- 應用程序 B 要求使用者在更改電子郵件地址之前驗證現有密碼。
- 應用程序 C 要求使用者驗證現有密碼並要求管理員批准更改電子郵件地址。
使用管理 API，你可以構建一個自訂服務，通過調用必要的 API 以正確的順序來協調這些要求。你甚至可以將管理 API 與你的服務的 API 結合起來，以實現複雜的工作流程。以應用程序 C 為例：
- 使用者在應用程序 C 中點擊「更改電子郵件」，這會向你的服務發送請求
POST /email-change-requests。它會創建一個新的電子郵件更改請求並返回識別符foo。 - 應用程序 C 向使用者顯示一個對話框，要求他們輸入現有的密碼。
- 使用者輸入密碼，應用程序 C 向你的服務發送請求
PATCH /email-change-requests/foo，附帶密碼。在背景中，你的服務會通過調用管理 APIPOST /users/{user_id}/verify-password驗證密碼。 - 如果密碼正確，你的服務會在電子郵件更改請求
foo中創建一條成功驗證記錄。 - 在管理面板中，管理員可以使用
GET /email-change-requests?status=pending查看待處理的電子郵件更改請求。 - 如果管理員批准請求，管理面板會向你的服務發送請求
PATCH /email-change-requests/foo，附帶管理員的批准。 - 然後你的服務會調用管理 API
PATCH /users/{user_id}來更新使用者的電子郵件地址。如果無法更新電子郵件地址，管理 API 將返回錯誤，你的服務可相應地處理它。
注意在上述例子中，我們的終端使用者從未直接與管理 API 互動。相反，他們與應用程序 C 互動，而應用程序 C 在背景中協同管理 API 調用以實現所需的工作流程。
優秀的管理 API 應該是什麼樣的？
- RESTful：遵循 RESTful 原則，使 API 預測性強且易於使用。
- 以資源為導向：將資源表示為名詞，並使用 HTTP 方法對它們執行操作。
- 一致性：使用一致的命名約定、錯誤處理和響應格式。
- 安全性：實施適當的認證 (authentication) 和授權 (authorization) 機制以保護 API。
- 文件化：提供清晰明確的文件說明 API 的使用方法，包括示例和用例。
- 兼容性：在引入 API 的新版本時確保向後兼容。
- 全面性：涵蓋所有必要的操作以有效地管理 IAM 資源。
還有其他方面，如性能和可擴展性，更多與基礎設施相關，而不是 API 設計本身。然而，在實踐中，一個好的管理 API 應考慮這些方面。