Postman API Catalogのベストプラクティス

API Catalogを使うと、エンジニアリングチームは組織内のすべてのAPIとサービスを1か所で把握できます。APIがどのインフラストラクチャにデプロイされているかにかかわらず、開発、テスト、本番など、すべての環境を含めて組織全体のAPIの状況を確認できます。

API CatalogにはAPIガバナンスが組み込まれており、中央の管理チームは、Postmanアプリでの開発中にはAPI仕様を通じて、CIではPostman CLIを通じてルールを適用できます。また、API CatalogはAIを活用することを前提に設計されています。PostmanのAgent Modeを使ってAPI Catalogを調べることで、システムアーキテクチャを理解し、主要な指標を確認したり、問題が発生した際に原因を調査したりできます。

GitHub、CLI、Collections、Environments、Flows、Insights、Mocks、Monitor、Specs、Governance、Securityの情報がすべてAPI Catalog Serviceビューに集約される仕組みを示しています。

API Catalogには何が含まれていますか？

API Catalogには、Postman環境内にある、Gitと接続されたすべてのPostman Workspaces（Projects）が自動的に一覧表示されます。エンジニアリングチームがPostmanワークスペースをソースコードに接続すれば、API Catalogに追加するための特別な操作は必要ありません。

API Catalogには、組織全体の情報が集約されます。適切なユーザーグループの権限を持つユーザーは、API Catalog全体を確認できます。通常は、社内のプラットフォームエンジニアリンググループやStaff／Principalレベルのエンジニアが該当します。ユーザーがワークスペースへのアクセス権を持たず、このグループにも所属していない場合は、アクセス権のあるプロジェクトのみが表示されます。

API Catalogを使用

API Catalogにはカタログリスト、ガバナンスグループ、システム環境の3つのコアコンポーネントがあります。

1. Catalog List

Catalog Listでは、複数の項目を使ってAPIを絞り込んだり、並べ替えたりできます。信頼できるAPIの一覧を維持するため、管理対象のAPIを示すタグを決めておくことを推奨します。また、API Catalogでは、Postmanに登録されているユーザー情報や、コードの所有者情報から、APIの担当者を特定できます。

API Catalogでは、フィルターとタグを組み合わせたビューを作成できるため、確認したい情報をまとめたビューにすぐに切り替えられます。Catalog Listでは複数の項目をまとめて表示でき、必要に応じて各項目の表示／非表示を切り替えられます。

ヒント：API CatalogにAPIを追加する前に、タグの分類方法を決めておきましょう。まず、組織でAPIをどのように分類するかを反映した、一貫性のあるタグを定義します。たとえば、ドメイン（payments、identityなど）、成熟度（stable、beta、deprecate など）、コンプライアンスの対象範囲（pci-compliant、internal-onlyなど）、担当チームといった基準でタグを設定できます。最初から一貫したルールでタグを設定しておくことで、APIの絞り込み、ガバナンスのグループ分け、保存したAPI Catalogのビューをより効果的に活用できます。APIを追加した後からタグの分類方法を整備するのは、はるかに難しくなります。

2. ガバナンスグループ

ガバナンスグループでは、OpenAPIやAsyncAPIなどのAPI仕様に適用するルールを作成し、適用できます。複数のAPI仕様をグループとしてまとめ、同じルールを適用できます。たとえば、外部公開APIには1つのルールセットを、社内のデータAPIには別のルールセットを適用できます。

PostmanでAPIを設計する開発者は、これらのルールをPostmanアプリ内で確認できます。Postman CLIではルールを取得してCIパイプラインで適用でき、違反があった場合にリリースをブロックするか、警告だけを表示するかを設定できます。また、ガバナンスルールを使ってAPIをスコアリングし、組織全体で定めたガバナンス方針にどの程度準拠しているかを確認することもできます。

ヒント：チームのオンボーディングを始める前に、ガバナンスグループを設定しましょう。ガバナンスルールは、開発者がAPI Catalogで作業を始めた後ではなく、事前に定義しておくことで最も効果を発揮します。幅広いエンジニアリングチームに展開する前に、少なくとも組織の基本的なLintルールを含むガバナンスグループを設定します。APIの利用対象に応じてガバナンスグループを分けることも検討しましょう。外部公開APIにはより厳格なルールセットを、社内のサービス間で利用するAPIには比較的柔軟なルールセットを適用することで、社内の開発スピードを妨げることなく、必要な領域に適切なレベルのガバナンスを適用できます。

3. システム環境

システム環境は、APIがデプロイされている実際のインフラストラクチャ環境（本番、ステージング、ベータなど）をPostman上で表すためのものです。システム環境を作成することで、Postmanのツールや分析システムが、APIに関するデータを環境ごとに正しく集約できるようになります。

よくあるケースとして、CI環境で複数のAPIにまたがる統合テストを実行する場合があります。システム環境がないと、テストをどの環境で実行したのかを判別しにくくなります。ローカル環境で実行したテストもあれば、ベータ環境で実行したテストもある、といった状況が考えられます。CIの設定でシステム環境を指定すれば、こうした問題を解消し、テスト結果を環境ごとに正しくまとめて、各APIの動作状況を確認できます。MonitorsやInsightsなど、ほかのPostmanツールについても同様です。

ヒント：テストの実行やMonitorsの設定を始める前に、システム環境を定義しましょう。システム環境は、インテグレーションテストの実行やMonitorsの設定を始める前に用意しておくことで、最も効果的に活用できます。システム環境がないと、テスト結果、Monitorの実行結果、Insightsのデータに環境の情報が付かず、適切に集約できません。組織でAPI Catalogの運用を始める前に、少なくとも本番、ステージング、開発の各環境を定義しておきます。CIパイプラインを設定する際は、Postman CLIの各コマンドで適切なシステム環境の識別子を指定し、すべての実行結果に正しい環境情報が付くようにします。

APIビュー

API Catalogには、組織全体のすべてのAPIとサービスが一覧表示されます。一覧からAPIをクリックすると、そのAPI専用のビューが開きます。このビューでは、開発、テスト、本番の各環境について、Postmanが現在把握しているすべてのデータを確認できます。

ここからPostmanワークスペースやAPIのソースコードに移動したり、稼働状況を示す主要な指標を詳しく確認したり、Insightsによって生成されたAPIの依存関係グラフを確認したりできます。Postman Insightsを統合している場合、API Catalogのビューには、Postmanで適切に管理されていないシャドウエンドポイントも表示されます。こうしたエンドポイントは、PostmanコレクションやAPI仕様に含まれていない可能性があります。

PostmanのAgent ModeはAPIビュー内でも使用できます。適切なアクセス権があれば、APIの状態を確認した後、そのまま実装作業に進むことができます。

APIとサービスを発見

API Catalogでは、API Gateway、Cluster Watcherサービス、Postman Insights、既存のPostmanワークスペースなど、複数の情報源からサービスを発見できるため、すぐに利用を始められます。これらの仕組みを使うことで、現在Postman環境で管理されていないAPIを見つけ、API Catalogに追加できます。オンボーディングのワークフローでは、PRを自動的に作成し、該当するAPIの所有者のリポジトリに送ることもできます。

1. API CatalogとAPI Gatewayの統合

多くの組織では、API Gatewayを接続することが、包括的なAPI Catalogをすばやく構築する方法です。本番環境にデプロイされたAPIはすべてGatewayを経由するため、チームがドキュメント化したAPIだけでなく、本番環境で実際に稼働しているAPI全体をすぐに把握できます。

Postmanは、Amazon API Gateway、Apigee API Management、Azure API Management、IBM API Connectなど、主要なプロバイダーのGatewayとの統合をサポートしています。接続すると、Gatewayを通じて発見されたAPIがAPI Catalogに自動的に表示され、API Catalogのビューから直接オンボーディングのワークフローを開始できます。API Gatewayの接続についての詳細は、ドキュメントをご覧ください。

API Gateway Integration、Postman Insights Agent、Postman Workspace、Cluster Watcherの統合オプションが表示されたサービス検出パネル。

2. Cluster Watcherを使ってサービスを継続的に発見

Cluster Watcherはインフラストラクチャを継続的に監視し、新しいサービスや変更されたサービスを検出して、API Catalogに自動的に表示します。サービスを手作業で探して追加する必要がありません。特に、エンジニアリングチームが正式な周知プロセスを経ずに新しいサービスを頻繁に作成する組織で役立ちます。

ヒント：Cluster Watcherが新しいAPIを見つけたら、オンボーディングのワークフローを開始しましょう。Cluster Watcherが新しいAPIやサービスを検出したら、それをきっかけに担当チームへ連絡し、一連のオンボーディングのワークフローを開始します。これにより、API Catalogを正確な状態に保ちながら、すべてのサービスを継続的に管理する習慣を組織に定着させることができます。

3. Postman Insightsを使ってシャドウエンドポイントを発見

Postman InsightsをAPI Catalogに接続し、各環境の実際のトラフィックを分析します。Insightsでは、API Catalog内のどのコレクションやAPI仕様にも含まれていないにもかかわらず、実際にトラフィックを受けているAPIエンドポイントをシャドウエンドポイントとして検出できます。シャドウエンドポイントは、テストもドキュメント作成もされておらず、ガバナンスルールも適用されないため、APIガバナンス上のリスクとなります。

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

4. Postmanワークスペースを接続してAPI Catalogを最新の状態に保つ

API Catalogには、組織内でGitと接続されているPostmanワークスペースが自動的に表示されます。API Catalogの情報を正確かつ最新の状態に保つため、各チームはワークスペースをソースコードのリポジトリに接続します。これにより、開発者がドキュメントを手作業で更新したときだけでなく、変更がマージされるたびに各APIの実際の状態がAPI Catalogに反映されます。

API CatalogでAgent Modeを活用

API Catalogは、AIを活用することを前提に設計されています。問題を調査したり、カバレッジを確認したり、不足している情報を特定したりするためにAPIビューを手作業で確認する代わりに、Agent Modeを使って自然言語でAPI Catalogのデータを検索・調査し、必要な操作まで実行できます。

自然言語でAPI Catalogを探索

Agent Modeを使うと、どこを確認すればよいか分からなくても、API Catalog全体を検索して、組織内のAPIに関する質問への回答を得られます。

コンテクスト	プロンプト
API Governance	「API CatalogにあるAPIのうち、現在ガバナンスルールに違反しているものはどれですか？」
カバレッジ	「API CatalogにあるAPIのうち、対応するOpenAPI仕様がないものはありますか？」
成熟度	「非推奨のタグが付いているものの、Insightsでは現在もトラフィックが確認されているAPIはどれですか？」
所有者	「Identityサービスを担当しているのはどのチームですか？最後に更新されたのはいつですか？」
依存関係	「Payments APIはどのサービスに依存していますか？」

Agent Modeを使ってエラーや稼働状況に問題があるサービスを調査

API Catalog内のサービスで、Monitorの失敗、Insightsでのエラーの急増、ガバナンススコアの低下など、稼働状況の悪化が確認された場合、Agent Modeを使えば複数のツールを行き来せずに問題を切り分けることができます。

例：「InsightsでCheckout APIのエラー率が高くなっています。直近ではどのようなエラーが発生していますか？また、最近のAPI仕様やコレクションの変更と関連がありますか？」

Agent ModeはInsightsのデータを確認し、関連するワークスペースの最近の変更履歴を調べ、API仕様の変更とエラーの急増が同じタイミングで発生していないかを確認します。そのうえで、考えられる原因と問題を解消するための次の対応を提示します。

Agent Modeを使ってAPI Catalogから直接修正を開始

Agent Modeでは、同じ会話の中で問題の診断から対応まで進められます。API仕様にエンドポイントが含まれていない、コレクションとAPI仕様が一致していない、テストカバレッジが不足しているといった問題を特定すると、Agent Modeがユーザーに代わって修正案を作成したり、プルリクエストを作成したり、Postmanアセットを更新したりできます。

例：「Watcherサービスで、Refunds APIの仕様に含まれていない新しいエンドポイントPOST /api/v2/refundsが見つかりました。正しいリクエストボディとレスポンススキーマを指定してAPI仕様に追加し、PRを作成してください。」

ヒント：Insightsで検出されたシャドウエンドポイントにAgent Modeで対応しましょう。InsightsによってAPI Catalogのビューにシャドウエンドポイントが表示されたら、Agent Modeを使ってすぐに修正を開始できます。「API CatalogにUserサービスのシャドウエンドポイントが3つ表示されています。これらを既存のOpenAPI仕様に追加し、それぞれのエンドポイント用にテストコレクションを生成してください。」

主なビジネス成果

このガイドで紹介したベストプラクティスを実践することで、次の3つの重要な成果が得られます。

自動化によってすべてのAPIを把握：API Gatewayを接続し、Cluster Watcherサービスを有効にして、ワークスペースをGitに接続することで、各チームが手作業で更新しなくても、API Catalogを最新の状態に保つことができる。
ボトルネックを生まないガバナンス：チームのオンボーディングを始める前にガバナンスグループとタグのルールを設定することで、手作業によるレビューに頼るのではなく、あらかじめ定めた基準をCIで自動的に適用できる。
AIエージェントが活用できるAPI Catalog：API仕様、メタデータ、環境のコンテキストをAPI Catalogに集約することで、Agent Modeがサービスの調査、生成、修正に必要な情報を参照できるようになる。開発者が組織内のAPIについて一から説明する必要もなくなる。