マネジメント API (Management API) とは？
マネジメント API (Management API) の定義は、使用しているソフトウェアやサービスによって異なる場合があります。アイデンティティおよびアクセス管理 (IAM) のコンテキストでは、通常、IAM 関連のリソースをプログラムで管理できる一連の API を指します。例えば、ユーザー、アプリケーション、ロール、権限、組織などです。
名前が具体的な実装を指定しているわけではありませんが、マネジメント API (Management API) は、その特性上、通常 RESTful です。それは、リソースとそれに対して実行できる操作を正確に定義しているためです。例えば、POST /users を見ると、この API コールが新しいユーザーを作成することを期待できます。
マネジメント API (Management API) が重要な理由は？
マネジメント API (Management API) は、IAM システムの上に、ユーザーインターフェースの下に別の抽象化レイヤーを作ります。これにより、開発者は IAM リソースの管理を自動化することができ、いくつかのシナリオで特に有用です：
1. 自動化
名前が示す通り、マネジメント API (Management API) を使用すると、ユーザーインターフェースを手動でクリックする代わりに、コードでリソースを管理できます。大量のユーザー、アプリケーション、またはロールを管理する必要がある場合に特に有用です。例えば、スクリプトを書いて CSV ファイルからユーザーをインポートし、適切なロールと権限を割り当てることができます。
2. 統合
マネジメント API (Management API) は、サービス間 (またはマシン間) のコミュニケーションを標準的に行う方法を提供します。IAM システムと通信する必要がある複数のサービスを持っている場合、各サービスにカスタム統合を実装する代わりに、API コールを組み合わせてすべてのサービスで使用できるように設計されたマネジメント API (Management API) を使用できます。例えば、特定のロールの下にあるすべてのユーザーをリストする必要があるサービスは、GET /roles/{role_id}/users を呼び出すことでこれを実行できます。
3. コンポジションおよび機能拡張
ビジネス要件の多様性により、IAM システムが必要なすべての機能を提供できない場合があります。特に複雑なアクセス制御要件に関してはそうです。マネジメント API (Management API) は、基盤となるプラットフォームやアーキテクチャを変更することなく、既存の IAM システムの上にカスタム機能を構築することを可能にします。
一般的な例を見てみましょう：エンドユーザーがメールアドレスを変更する必要があります。異なるアプリは異なる要件を持っているかもしれません：
- アプリ A は、ユーザーに古いメールと新しいメールの両方を確認するよう要求します。
- アプリ B は、メールアドレス変更の前に既存のパスワードを確認するようユーザーに要求します。
- アプリ C は、既存のパスワードと管理者によるメール変更の承認を確認するようユーザーに要求します。
マネジメント API (Management API) を使えば、これらの要件を適切な順序で必要な API を呼び出すことによって調整するカスタムサービスを構築できます。さらに、マネジメント API (Management API) をサービスの API と組み合わせて複雑なワークフローを実現することもできます。App C を例にとってみましょう：
- ユーザーが App C の「メール変更」をクリックすると、リクエスト
POST /email-change-requestsがあなたのサービスに送信されます。これにより、新しいメール変更リクエストが作成され、識別子fooが返ります。 - App C はユーザーにダイアログを表示し、既存のパスワードを入力するように求めます。
- ユーザーがパスワードを入力し、App C はリクエスト
PATCH /email-change-requests/fooをサービスに送信します。サービスはバックグラウンドでマネジメント API (Management API)POST /users/{user_id}/verify-passwordを呼び出してパスワードを確認します。 - パスワードが正しければ、サービスはメール変更のリクエスト
fooに成功した検証記録を作成します。 - 管理パネルで、管理者は保留中のメール変更リクエストを
GET /email-change-requests?status=pendingで確認できます。 - 管理者がリクエストを承認すると、管理パネルはリクエスト
PATCH /email-change-requests/fooをサービスに管理者の承認付きで送信します。 - その後、サービスはマネジメント API (Management API)
PATCH /users/{user_id}を呼び出してユーザーのメールアドレスを更新します。メールアドレスを更新できない場合、マネジメント API (Management API) はエラーを返し、サービスがそれを適切に処理できます。
上の例では、エンドユーザーはマネジメント API (Management API) と直接やり取りすることはありません。代わりに、App C とやり取りし、バックグラウンドでマネジメント API (Management API) コールが調整されています。
優れたマネジメント API (Management API) はどのようなものか？
- RESTful: RESTful の原則に従い、API を予測可能かつ使いやすくします。
- リソース指向: リソースを名詞として表し、HTTP メソッドを使用してそれらに対するアクションを実行します。
- 一貫性: 一貫性のある命名規則、エラーハンドリング、レスポンスフォーマットを使用します。
- 安全性: 適切な認証および認可メカニズムを実装して API を保護します。
- 文書化: API の使用方法、例、ユースケースを含む明確で簡潔なドキュメンテーションを提供します。
- 互換性: 新しいバージョンの API を導入する際には後方互換性を保証します。
- 包括性: IAM リソースを効果的に管理するために必要なすべての操作を網羅します。
パフォーマンスやスケーラビリティなど、インフラストラクチャに関連する他の側面もありますが、実際には、優れたマネジメント API (Management API) はこれらの側面も考慮するべきです。