什么是管理 API？
管理 API 的定义可能因所使用的软件或服务而异。在身份和访问管理 (IAM) 的背景下，管理 API 通常指一组允许你以编程方式管理 IAM 相关资源的 APIs。例如，用户、应用程序、角色、权限、组织等。
虽然名字没有具体指明实现方式，但鉴于其明确定义资源和可以对其执行的操作的特性，管理 API 通常是 RESTful 的。这就是说，当你看到 POST /users 时，可以预期这个 API 调用将创建一个新用户。
为什么管理 API 很重要？
管理 API 在 IAM 系统之上但在用户界面之下创建了一个独立的抽象层。这使得开发人员可以自动化地管理 IAM 资源，这在以下几种情况下尤其有用：
1. 自动化
如其名所示，管理 API 允许你使用代码来管理资源，而不是通过用户界面手动点击。这在需要管理大量用户、应用程序或角色时尤其有用。例如，你可以编写一个脚本从 CSV 文件导入用户，并将其分配到正确的角色和权限。
2. 集成
管理 API 为服务对服务的通信或机器对机器的通信创建了一种标准方式。当你有多个服务需要与 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 交互，后者在后台协调管理 API 调用以实现所需的工作流。
优秀的管理 API 应该是什么样的？
- RESTful：遵循 RESTful 原则，使 API 易于预测和使用。
- 资源导向：将资源表示为名词，并使用 HTTP 方法对其执行操作。
- 一致性：使用一致的命名约定、错误处理和响应格式。
- 安全性：实施正确的认证 (Authentication) 和授权 (Authorization) 机制来保护 API。
- 文档化：提供清晰简洁的文档，说明如何使用 API，包括示例和用例。
- 兼容性：在引入新版本的 API 时确保向后兼容。
- 全面性：涵盖所有必要的操作，以有效管理 IAM 资源。
还有其他方面，如性能和扩展性，它们更多地与基础设施相关，而不是 API 设计本身。然而，在实践中，一个好的管理 API 应该也考虑这些方面。