POSTMAN BEST PRACTICES

社内APIの公開と発見

Building quality APIs has never been more important. At Postman, we believe being API-first is the key to innovation in the AI era. We built Postman Best Practices to share the foundational ideas Postman is built on and enable you to do your best work.

現代のエンタープライズでは、社内で構築するAPIが重要な戦略的資産となっています。Postmanは、組織内のすべての開発者やAIエージェントが、必要なときに適切なAPIを見つけ、評価し、スムーズに利用できることが重要だと考えています。APIを探すために手間をかけたり、推測に頼ったり、特定の人しか知らない情報をあてにしたりする必要はありません。

社内APIの活用がうまくいかない原因の多くは、APIの設計そのものではなく、開発者が必要なAPIを見つけられないことにあります。API仕様と本番環境の実態が一致しなくなったり、既存のサービスに気づかず同じような機能を重複して開発したりします。また、AIコーディングツールは社内のAPIコントラクトを参照できないため、誤ったコードを生成することがあります。

この章では、常に正確な情報を自動的に維持できるPrivate API Networkの構築方法、各領域を担当するチームの編成方法、そして開発者とAIエージェントのどちらも必要なAPIを見つけて活用できる環境の整え方を紹介します。

Abhinav Asthana

Abhinav Asthana

Postman CEO and Co-founder

Ankit Sobti

Ankit Sobti

Postman Field CTO and Co-founder

社内APIを適切に公開・共有することで、開発者やAIエージェントは、必要なときに適切なAPIを見つけ、自分たちの用途に合うかを確認して利用できます。Postman Private API Networkを活用すれば、APIに関する情報が組織内に分散する「APIサイロ」を解消し、必要な社内APIを正確かつスムーズに見つけられるようになります。

現代のエンタープライズでは、APIを見つけやすくするためにドキュメントを手作業で整備するのではなく、Gitを基盤としたワークフローによって、コードから利用まで信頼できる情報を提供することが重要です。Organizationsによるチーム構成とワークスペースを中心とした自動化を活用することで、Private API Networkを常に正確な状態に保ち、本番環境と同期させ、開発者にもAIを活用したコーディングにも利用できる環境を整えられます。

API提供者はPrivate API Networkに公開し、API利用者はそこからAPIを見つけます。図。

Organizationsとチームの設定

Private API Network（PAN）は1つのチームでも管理できますが、組織全体でAPIを見つけやすくするには、単なる「APIの一覧」ではなく、「どのチームがどの機能を提供しているか」が分かる形で整理する必要があります。

  • Organizationsを有効にしていない場合：すべてのワークスペースを1つのチームで管理します。タグを使ってAPIを絞り込んだりグループ化したりできますが、画面上では1つの一覧として表示されます。
  • Organizationsを有効にしている場合（強く推奨）：実際のエンジニアリング組織に合わせてPostman上の構成を整理できます。決済やID管理など、担当領域ごとにチームを作成し、それぞれのワークスペースをまとめて管理できます。

Organizationsを使うと、API公開の承認を一部の管理者に集中させず、コードやAPIを最もよく理解している各チームに任せることができます。同時に、組織全体を管理する役割も維持できます。Organizationsの詳細は、ドキュメントをご覧ください。

ロールスコープAPI公開に関する役割
プライベートネットワークマネージャー組織全体組織全体の基準を定め、Private API Network全体を管理します。
チームマネージャー各チーム担当チームのワークスペースを確認し、Private API Networkに公開できる状態かどうかを判断して承認します。

このように構成すると、必要なAPIを直感的に見つけられます。たとえば、「ユーザープロファイル」のエンドポイントを探している開発者が、500ものワークスペースを一つひとつ探す必要はありません。［Identity Team］＞［User Service Workspace］とたどるだけで、目的のAPIにアクセスできます。

APIを利用するためのワークスペース設定

各プロジェクトやAPI群には、PostmanのNative Gitを使ってソースコードと連携した専用のPostmanワークスペースを用意します。これにより、APIドキュメントをコードと一緒に管理し、CLIで更新を自動化できるため、コードの変更にドキュメントの更新が追いつかない状態を防げます。

ワークスペースをGitに接続

Postmanワークスペースを、Gitで初期化したローカルファイルシステムに直接接続します。この連携は、クラウドでもセルフホストでも、すべてのGitプロバイダーで利用できます。Postmanを既存の開発ワークフローに直接組み込んで作業できます。

  • ファイルを一元管理：コレクション、API仕様、テスト、モックは、リポジトリ内の/postmanディレクトリにファイルとして保存されます。
  • Gitを使った開発フロー：普段使っているブランチやプルリクエストの運用方法で、APIの変更を管理できます。
  • コードとAPIを同期して開発：コードとPostmanアセットを1つのPRでまとめて変更できるため、APIの実装とドキュメントが食い違うのを防げます。

必要な情報を1か所に集約

APIを見つけた開発者がすぐに利用できるように、ワークスペースには必要な情報を揃えておくことが重要です。開発者がPrivate API Networkでサービスを見つけたとき、少なくとも次の情報が含まれているようにします。

  • 仕様： APIの動作を定義する正式なコントラクトです。APIに関する信頼できる唯一の情報源として管理します。
  • コレクション：あらかじめ設定されたリクエストを用意し、API利用者が［Send］をクリックするだけですぐにレスポンスを確認できるようにします。
  • 環境：base_urlやapi_versionなどの変数をあらかじめ定義し、API利用者が必要な設定を推測しなくても利用できるようにします。

APIを見つけやすくするメタデータ

Private API Networkでワークスペースを検索しやすくし、必要な情報をすぐに判断できるように、タグと説明を効果的に設定します。

  • 説明：単に「Billing API」のような名前を記載するだけでなく、何のために使うAPIなのかを具体的に示します。たとえば、「北米地域でPCI準拠のトランザクションを処理するために使用します」のように記載します。
  • タグ：Internal-Only、v2-Deprecated、PCI-Compliant、gRPCなど、APIの用途や状態が分かるタグを使用します。
  • 公開範囲：ワークスペースをPrivate API Networkへの公開候補にできるよう、公開範囲を「Team(Org)」に設定します。

（オプション）API利用者向けに別のディスカバリーワークスペースを設定

API利用者向けに、専用のディスカバリーワークスペースを別途用意することもできます。次のような場合におすすめです。

  • 幅広く公開するコレクションを一部に限定したい場合。たとえば、アプリ固有のエンドポイントやテスト用コレクションが共有されないようにしたい場合です。
  • 関連する複数のリポジトリ（ワークスペース）にあるコレクションを、API利用者向けの1つのワークスペースにまとめたい場合。

API利用者向けに別のディスカリーワークスペースを設定する場合は、次の方法を推奨します。

  1. Gitと連携したワークスペースは、直接関係するチーム内で共有します。
  2. より幅広く利用してもらうAPIだけを選び、API利用者がすぐに使えるコレクションを作成します。
  3. そのコレクションを別のディスカバリーワークスペースにフォークし、フォークの自動同期を有効にします。
  4. 関連する複数のリポジトリから、同じディスカバリーワークスペースに複数のコレクションをフォークすることもできます。
  5. ディスカバリーワークスペースをPrivate API Networkに公開します。

この方法なら、APIの開発に必要な複雑な情報と利用者向けの情報を分けて管理できます。社内専用やアプリ固有のエンドポイントが誤って利用されるのを防ぎながら、API利用者にはよりシンプルで使いやすい環境を提供できます。

ワークスペースの継続的な更新を自動化

Postman CLIを使うと、Postmanワークスペースをデプロイ先として扱い、コードがマージされたときや特定の環境にデプロイされたときに、テスト、Lint、同期を実行できます。これにより、開発者が手作業でドキュメントを更新する必要がなくなり、CI/CDパイプラインを通じてリポジトリとPrivate API Networkの内容を常に一致させることができます。

実装手順

  1. インストールと認証：Postman CLIをCI環境（GitHub Actions、GitLab CI、Jenkinsなど）に追加します。CIプロバイダーで保護されたシークレットとして保存したPostman API Keyを使って認証します。
  2. API仕様のLint：プルリクエストごとに、OpenAPI仕様に対してpostman api lintを実行するステップを追加します。「Error」レベルのガバナンス違反が検出された場合はビルドが失敗するように設定し、設計上の問題をマージ前に検出します。
  3. ワークスペースとの同期：mainブランチへのマージが成功したら、postman workspace pushコマンドを実行します。このコマンドは/postmanディレクトリをスキャンし、その内容に合わせてPostmanワークスペースのコレクション、API仕様、環境を更新します。
  4. （任意、推奨）コントラクトテストの実行：デプロイの判定基準として、ステージング環境に対してpostman collection runを実行します。これにより、デプロイしたコードが、ワークスペースに保存されている実行可能なドキュメントで定義された内容に準拠していることを確認できます。

この仕組みにより、APIドキュメントの更新を開発とは別の作業として行うのではなく、開発プロセスの中で自動的に反映できます。手作業で更新しなくても、開発者が信頼できる最新のAPI情報を提供し続けられます。

Private API Networkへの公開

Private API Networkは、ほかのチームが利用するAPIを見つけるための場所です。APIは［Home (Org) ＞ Team ＞ Workspace］の階層で整理されており、画面左上の切り替えメニューから［Private API Network］を選択してアクセスできます。

  1. Private API Network：決済チームの開発者が、processing-apiワークスペースをPrivate API Networkに追加するよう申請します。
  2. チームでの承認：決済のチームマネージャーが申請内容を確認し、承認します。
  3. APIを探しやすい階層構造：Private API Networkでは、次のように整理された構成でワークスペースを確認できます。
    • 決済チーム
      • クレジットカードAPI（ワークスペース）
      • 返金API（ワークスペース）
    • ID管理チーム
      • 認証API（ワークスペース）
  4. タグによる絞り込み：ワークスペースにさまざまなtagsを追加すると、Private API Networkにも表示されます。タグで絞り込むことで、条件に一致するワークスペースだけを表示でき、目的に応じて柔軟にワークスペースをグループ化できます。

Private API Networkの情報を活用

Private API Networkは、整理されたAPIの一覧を確認するためだけの場所ではありません。PostmanのUI、社内のAIアシスタント、IDEなど、開発者が普段作業している場所から必要なAPI情報を利用できるようにする役割もあります。

APIに関する単一の信頼できる情報源（SSOT：Single Source of Truth）をPrivate API Networkに集約することで、エンジニアは普段作業しているさまざまな場所から、必要なときにAPIを見つけられるようになります。

  1. 直接参照：画面左上のナビゲーションメニューから［Private API Network］を選択します。Teamsごとに担当領域に沿って整理された全体像を確認でき、検証済みのワークスペースや関連情報を参照できます。Teamsごとに担当領域に沿って整理された全体像を確認でき、検証済みのワークスペースや関連情報を参照できます。
  2. 検索バー：グローバル検索バー（Cmd/Ctrl + K）を使って、APIをすぐに検索できます。
    • 検索結果の横に表示される紫色のチェックマークは、そのAPIがPrivate API Networkで検証済みであることを示します。
    • 検索メニューで「Private Network」フィルターを使用すると、パブリックAPIや検証されていない社内APIを除外し、承認済みのサービスだけを対象にできます。
  3. Postman AI：右側のサイドバーにあるPostman AIアシスタントを利用します。「決済の返金APIはどのチームが管理していますか？」や「Identityサービスの認証方法を教えてください」など、自然言語で質問できます。AIはPrivate API Networkの情報を利用して、質問の文脈に応じた正確な回答を提供します。
  4. 外部AIやIDEとの連携：Postman MCP（Model Context Protocol）Serverを使って、Claude、Cursor、VS Codeなどの外部コーディングツールを社内のAPIカタログに接続できます。
    • APIの検索：MCPサーバー経由でPostman Search APIを利用できるようにし、Claude Code、Cursor、Vercelなど主要なAIツールとの公式インテグレーションを活用することで、外部のAIエージェントからPrivate API Networkをリアルタイムに検索できます。
    • コード生成：AIエージェントは、検証済みのワークスペースから正確なAPI仕様やSDKの情報を取得できます。開発者はエディターを離れることなく、より高品質で本番環境に対応したコードを生成できます。
Private API Networkと、ワークスペースの検索結果を表示するAIサイドバー。スクリーンショット。

主な成果

このガイドの内容を実践することで、次の3つの重要な成果が得られます。

  1. 自動化によって正確で信頼できる情報を維持：Private API Networkは人の記憶に頼るのではなく、CI/CDパイプラインによって更新されるため、常に正確な情報を維持できます。
  2. チームごとに管理することで効率化：各チームマネージャーが担当領域を管理することで、承認作業が一部の担当者に集中するのを防げます。また、コードを最もよく理解しているチームが、公開できる状態かどうかを確認できます。
  3. AIが活用できる情報を整備：API仕様とメタデータを一元的に管理することで、Postman AIや外部IDEのAIエージェントが、正確で本番環境で利用できる品質のコードを生成するために必要な情報を提供できます。

その結果、開発者やAIエージェントがエンドポイントを探すために費やす時間を減らし、機能開発により多くの時間を使えるようになります。

使いながら理解するのが一番です。最初のワークスペースをPrivate API Networkに公開する →