API Governance

小規模なアプリ専用APIを構築する段階では、スピードが最優先されることが多いでしょう。仕様は軽く、フィードバックループは短く、変更も迅速です。しかし、このスピードの裏には代償があります。エンドポイントの仕様に一貫性がなくなったり、スキーマの検証が不足したり、フロントエンドチームが滞りなく開発を進めるには情報が不十分なケースが生じます。これらの小さなズレが積み重なると、後になって再作業やバグ修正が増え、チーム間の摩擦を引き起こします。

Postmanのガバナンス機能を活用すれば、こうした問題を早期に検出し、バックエンドとフロントエンドの整合性を維持しながら、APIの信頼性を高めることができます。

アプリ専用APIのガバナンス

アプリ専用APIを構築する場合、対象となるのは通常、特定のUIや社内システムなど単一の利用者です。この段階ではスピードが重視され、ドキュメントや仕様の完全性よりも、即時的な開発ニーズへの対応が優先されます。ただし、ガバナンスが軽視されると、パターンの不統一やバリデーション漏れ、エラー処理のばらつきなどが発生しやすくなります。その結果、フロントエンドチームが正確なエンドポイント情報を待たされ、リリースが遅れるといった問題が起きることがあります。

アプリ専用APIは、プロジェクト要求に合わせて短期間で開発されることが多く、API仕様は最小限で、実装後に生成されるケースもあります。これは、ゲートウェイ設定、認証、レート制限などの管理作業を支援するためです。利用者が通常ひとつのチームに限られるため、フィードバックループは短く、変更も迅速に行われます。

推奨プラクティス

• バックエンドとフロントエンドのチームがリアルタイムで共同作業できるよう、ワークスペースを設定する。
• コレクションを使ってAPIのプロトタイプを作成し、テストの実行、エンドポイントのモック、モニターの設定を行い、バックエンドチームとフロントエンドチームでAPIの動作を共有します。
• コレクションに型情報を追加し、正式な仕様作成前でもリクエストとレスポンスの構造を明確にする。
• ワークスペースレベルで軽量なガバナンスルールを適用し、スキーマ検証・必須フィールド・基本的なセキュリティチェックを自動的に確認する。
• 最終的な仕様はSpec Hubに保管し、デプロイ前の中央リファレンスとして管理する。インライン注釈を活用して、仕様レベルでリリース準備が整っているかを検証する。
• CI/CDパイプラインに検証プロセスを統合し、ステージング前に問題を検出する。

使いながら理解するのが一番です。APIガバナンスの設定を始めてみましょう。.

再利用可能APIのガバナンス

再利用可能なAPIでは、API利用者が増えるほど不整合による影響も広がるため、より厳格なガバナンスが必要です。アプリ固有APIとは異なり、多くの利用者への展開と長期的な保守性を重視します。

推奨プラクティス

• 共有ワークスペースを設定し、社内チーム・パートナー・外部開発者が共通の環境でオンボーディングできるようにする。コレクション、モックサーバー、ドキュメント、変更管理ルールを含め、API利用をセルフサービスで進められる構成を整える。
• Spec HubでAPIを設計し、OpenAPI 3.0またはAsyncAPI 2.0仕様を使用して包括的なスキーマを作成する。もしくは、実際の利用者によって検証されたコレクションから仕様を生成してもよい。
• コレクションを使用してAPIをプロトタイプ化・テスト・モック・モニタリングし、動作をチーム間で共有する。仕様から始める場合でも、現場でのフィードバックを得るためにコレクションを生成して活用する。仕様から設計を始める場合でも、コレクションを生成して実際の利用方法に照らして検証することで、有益なフィードバックを得られる。
• コレクションに型情報を追加し、正式な仕様作成前でもリクエストとレスポンスの構造を明確にする。
• ガバナンスルールエディタを使用し、Spectralベースのルールセットを適用して構造、命名規則、エラーハンドリングを一貫させる。これらのルールは自動的に検証を実行し、仕様レベルでの品質を保証する。
• 完成したAPI仕様は、デプロイ時に参照する情報を一元管理するため、Spec Hubに保存する。
• CI/CDパイプラインに検証プロセスを統合し、ステージング前に問題を自動検出する。

アプリ専用APIから再利用可能APIへの移行

多くの組織では、まずアプリ専用APIから開発を始め、時間の経過とともにそれらをより広く利用できる再利用可能APIへと発展させていきます。初期段階ではプロジェクト単位のスピード重視で構築されたAPIも、適切なプロセスを経て信頼性の高い共有サービスへと進化させることが可能です。

この変化を支援するのが、Postmanの段階的なガバナンスモデルです。

1. 再利用の候補となるAPIを特定する。複数のチームで活用できそうなAPIを選定し、専用のワークスペースに移動して、より厳密なガバナンスルールを適用します。
2. 標準を段階的に強化する。アプリ専用APIには軽量なガバナンスを適用しつつ、再利用可能APIにはより包括的なルールを導入します。各チームが自分たちのペースでAPIを成熟させることができます。
3. 自動コンプライアンスチェックを導入する。Postman CLI を活用して、CI/CDパイプライン内でAPIをガバナンス基準に沿って自動検証します。手作業でのレビューを減らし、品質を維持したままリリースサイクルを短縮できます。
4. 変更の通知を一元化する。ワークスペースアップデートを使って、APIの変更点・非推奨化・新機能を利用者に通知します。

APIガバナンスの中核としてAPI Catalogを活用

API Catalogを使うと、プラットフォームチームやガバナンスチームは、組織全体のAPIがガバナンス基準にどの程度準拠しているかをリアルタイムで把握できます。どのAPIがガバナンスルールに準拠しているか、どのAPIに違反があるか、また、どのAPIに仕様がまったくないかをAPI Catalogから確認できます。これにより、API仕様を個別にレビューするだけでなく、組織全体のAPIの状態を示す指標としてガバナンスを把握できます。

API CatalogのGovernance Groupsを使って、APIの利用対象に応じて異なるルールセットを適用します。たとえば、外部公開APIにはより厳格なルールを適用し、社内のサービス間で利用するAPIには比較的軽量なルールを適用できます。

推奨プラクティス

• チームのオンボーディングを始める前に、Governance Groupsを設定します。開発者がAPI Catalogで作業を始める前にガバナンスルールを定義しておくことで、より効果的に適用できます。
• APIの利用対象に応じて、Governance Groupsを分けることも検討します。外部公開APIにはより厳格なルールセットを、社内のサービス間で利用するAPIには比較的柔軟なルールセットを適用することで、社内の開発スピードを妨げることなく、必要な領域に適切なレベルのガバナンスを適用できます。

Postman Insightsを使った実行時のAPIガバナンス

APIの設計時やCIで適用するルールでは、構造上の問題を検出できますが、シャドウエンドポイントは検出できません。シャドウエンドポイントとは、実際にトラフィックを受けているものの、対応するAPI仕様やコレクションが存在しないAPIエンドポイントです。

Postman InsightsをAPI Catalogに接続すると、こうしたエンドポイントを自動的に検出できます。シャドウエンドポイントは、テストもドキュメント作成もされておらず、ルールセットも適用されないため、APIガバナンス上の問題となります。Insightsの詳細は、ドキュメントをご覧ください。

推奨プラクティス

• 毎週または隔週など、定期的にレビューを行い、Insightsで新たに検出されたシャドウエンドポイントを確認して対応の優先順位を判断します。
• 各シャドウエンドポイントの担当者を決め、オンボーディング用のPRを作成し、APIガバナンス上の問題が広がる前に解消します。

ヒント：Agent Modeを使ってシャドウエンドポイントを解消しましょう。プロンプト：「API CatalogにUserサービスのシャドウエンドポイントが3つ表示されています。これらを既存のOpenAPI仕様に追加し、それぞれのエンドポイント用にテストコレクションを生成してください。」

Organizationsを使って組織全体のガバナンスを設定

Postman Enterpriseプランでは、Organizationsを使ってガバナンスの適用を各組織に分散できます。1つのプラットフォームチームがすべてのAPI変更を承認するのではなく、各Organizationのチームマネージャーが担当領域のガバナンスを管理します。プライベートネットワークマネージャーが組織全体の基準を定め、チームマネージャーが担当領域でその基準を適用します。

Organizationを設定することで、組織の規模が拡大してもガバナンスの承認や適用がボトルネックになるのを防げます。Organizationsの詳細は、ドキュメントをご覧ください。