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が正しく運用されれば、それは企業にとって最もスケーラブルな成長機会になります。しかし、多くのパブリックAPIが失敗するのは、機能が劣っているからではなく、開発者体験（DX）が不十分だからです。開発者がAPIを見つけられない、統合方法を理解できない、あるいは認証が複雑すぎて途中で離脱してしまう ―― こうした問題が採用の最大の障壁になります。

ここでは、Postman上でAPIをより見つけやすくし、オンボーディングの摩擦を取り除き、開発者コミュニティとの関係を深めることで、APIの利用を促進する方法を紹介します。

Abhinav Asthana

Postman CEO and Co-founder

Ankit Sobti

Postman Field CTO and Co-founder

PostmanでのパブリックAPIコラボレーションは、新規および既存の顧客に再利用可能なAPIを提供したい企業向けのモデルです。企業にとってAPIは、収益を生み出す製品であり、ビジネス成長の推進力となります。一方、利用者にとってAPIは、イノベーションの原動力です。APIを通じて新しい製品やサービスを構築し、やがてはそのAPIを中心に開発者コミュニティが形成されます。

パブリックAPIのコラボレーションパターン

PostmanでのパブリックAPIコラボレーションは、主に次の3つの領域で行われます。ここでは、例として「配送会社のAPI」を用いて説明します。これらの領域は直線的なステップではなく、異なるチームがそれぞれの目的に応じて同時にAPIを利用・改善している状態として理解してください。

社内チームが、顧客が使いやすいように設計ガイドラインに基づいてAPIを設計・構築する
チームがPostmanネットワーク上でAPIを公開し、APIの進化に合わせて新しいコンテンツを継続的に発信する
開発者が自分のプライベートワークスペースでAPIを試し、実際に統合できるかを検証する

パブリックAPIのカスタマイズ。イラスト。

内部でのAPI設計と構築

外部公開を前提としたAPIを構築する際、最大の課題は「一貫性の維持」です。設計基準が定まっていないと、開発者にとって不自然で扱いにくいAPIになり、信頼性を損ねます。

たとえば配送会社がパブリック公開を前提に再利用可能APIを構築する場合、「住所検証」「配送ラベル発行」「配送追跡」などの機能をチーム単位で開発することになるでしょう。こうした機能を統合してわかりやすく提供するには、パラメーター命名規則、認証方式、HTTPステータスコード、エラーレスポンス構造などを共通化したAPIスタイルガイドが不可欠です。見た目の整合性やエラーメッセージの一貫性といった細部の品質が、最終的な開発者体験を左右します。

このような体制は、「Postmanベストプラクティス：内部APIコラボレーション」に示されている「プラットフォーム全体でのコラボレーション」モデルに近い形です。これにより、より統一された高品質な外部向けAPIを実現できます。

配送会社が成功するためには、まずすべての開発チームが共通のAPIスタイルガイドを定義し、それを基準に開発を進める必要があります。開発者は個人の開発者ワークスペースまたはチーム内プロジェクトスペースでAPIのイテレーションを行い、安定した段階でチームスペースへマージします。社内で定めた基準を満たしたAPIのみをパブリックスペースへ公開します。

ヒント：API利用者に、プロトコルに応じたコレクションとドキュメントを提供しましょう。Postman（v12以降）のパブリックワークスペースでは、REST、GraphQL、gRPC、MCPベースのAPIをサポートしています。パブリックAPIでこれらのプロトコルを使用している場合は、それぞれのプロトコルに適したコレクションとドキュメントをワークスペースに用意します。これにより、Time To First Call（初回APIコールまでにかかる時間）を短縮し、サポートへの問い合わせを減らすとともに、技術的な経験や専門分野が異なる開発者でもAPIを利用しやすくなります。

Postman APIネットワークへの公開

Postman APIネットワークは、新規および既存の顧客にAPIを届けるための強力なチャンネルです。Postman APIネットワークは月間数百万件の検索トラフィックを誇り、パブリックワークスペースを持つことが掲載の唯一の条件です。ただし、優れたAPIであっても、開発者に「見つけてもらえない」または「すぐに使い方が分からない」状態では採用されません。開発者がすぐに価値を感じられるように設計し、わかりやすく公開することが成功の鍵となります。APIを効果的に顧客へ届けるためには、次のステップを踏みましょう。

1. 自社の信頼性を示し、Postman上での存在を明確にする

まず、Postman API Networkで認証を受けましょう。認証を受けることで信頼性が高まり、開発者にもAPIを見つけてもらいやすくなります。Postman上で企業名に認証バッジが表示されることで、信頼できる正規の提供元であることを開発者に示せます。その結果、認証済みの企業は検索結果やオートコンプリートでより目立つ位置に表示されます。

さらに、自社の開発者ポータルに「Postmanで実行」ボタンを設置しておきましょう。多くの開発者はすでにPostmanを利用してAPIを設計・テストしているため、このボタンを押すだけでAPIをすぐに試すことができ、体験のハードルを大きく下げられます。

PayPalチームがどのように「Time to First Call（初回APIコールまでの時間）」を数時間から1分に短縮し、PostmanのパブリックAPIネットワークで最も利用されるAPIトップ10に入ったのかをご紹介します。ケーススタディを見る→

2. APIのオンボーディングを簡単にする

ほとんどのAPIは、特定の主要ユースケースが価値の大半を占めます。自社のAPIにとって最も重要なユースケースを特定し、それぞれをコレクション単位で整理して提供しましょう。たとえば配送会社であれば、「配送追跡」や「住所検証」などが代表的なユースケースになります。これらのコレクションを整備することで、開発者は主要な機能をすぐに試し、活用方法を理解できます。

APIで認可が必要な場合、それがオンボーディングで最初のハードルになることがよくあります。開発者が何度も問題に直面すると、そのAPIの利用を諦めて別のサービスを選んでしまう可能性があります。こうした問題を減らすため、ガイド付き認証を設定して、OAuthのようにワンクリックで進められる方法を含め、APIの認可手順を分かりやすく案内できるようにします。

さらに、Postmanのノートブック機能を使えば、実行可能なストーリー形式のAPI例を提供できます。たとえば、Moneris社は自社APIを使ってAIエージェントを構築する方法を示すノートブックを公開しています

AIエージェントなど、APIを使った実行可能なアプリケーションやワークフロー全体を共有するには、Flowを作成します。たとえばHubSpotは、通話を分析してタスクを作成するエージェントの構築方法を紹介するFlowを公開しています。

3. SDKを提供して、すぐにAPI連携を始められるようにする

PostmanのSDK Generatorを使って、パブリックAPIのクライアントSDKを生成して公開します。コレクションとあわせてSDKを公開することで、Time To First Call（初回APIコールまでにかかる時間）を大幅に短縮できます。SDKがあれば、開発者はHTTPリクエストを一から作成する代わりに、使い慣れた言語向けに用意されたライブラリを利用できます。

パブリックワークスペースと開発者ポータルにSDKのダウンロードリンクを追加し、API利用者がすぐにAPI連携を始められるようにします。SDK Generatorの詳細は、ドキュメントをご覧ください。

4. ユーザーに最新情報を届ける

開発者が自社のAPIをフォローすると、Postman上やメールを通じてワークスペースのアップデートで直接通知を受け取れるようになります。APIチームはこの機能を使って、新機能のリリース、仕様変更、新しいドキュメント公開などを開発者に即時で伝えられます

各APIの更新情報を公開すると、グローバルニュースフィードにも表示されます。利用者は更新情報に絵文字でリアクションしたり、コメントを投稿したりできます。これにより、利用者からのフィードバックやコミュニティの反応をリアルタイムに把握できます。

5. APIを継続的に改善する

Postmanでは、APIの利用状況や開発者の関与度を定量的に把握できます。閲覧数、APIコール数、レスポンスステータス、認可エラーの発生率などの指標をモニタリングすることで、開発者体験を継続的に最適化できます。

たとえば、401 Unauthorizedエラーが多発している場合は、Guided Auth（ガイド付き認証）を導入することで、開発者が正しく認証を行えるよう改善できます。その後、ワークスペースを更新することでこの改善を告知すれば、ユーザーの混乱やサポートコストを減らすことができます。

API利用者の活用パターン

開発者がAPIを効果的に使いこなすためには、発見から実装までの明確で導かれた道筋が必要です。包括的なサンプル、最新のドキュメント、そして活発なコミュニティサポートが欠けていると、興味を持った開発者であっても統合に苦労し、最終的には利用を断念してしまうことがあります。

パブリックAPIまたはパートナーワークスペース上でAPIを公開した後も、開発者側でのコラボレーションは続きます。ここでは、Postman上で一般的に見られる3つの代表的なAPI利用パターンを紹介します。

個人での評価

最も一般的なパターンは、開発者がコレクションをフォークしてAPIを試すケースです。自分のニーズに合うと判断した場合、その開発者はPostman上でAPIをフォローし、更新情報を受け取ったり、コメントやリアクションを通じてコミュニティと交流したりします。

チームでの統合

開発者が自社製品でAPIを採用することを決めた後は、そのコレクションをチームワークスペースに追加します。チーム全体でAPIをテストしたり、新しいユースケースを探ったりしながら、APIの更新情報やコミュニティでの議論に継続的にアクセスできるようになります。

コミュニティによる貢献

一部の開発者は、コレクションをフォークして改善点を加え、それを再びコミュニティへ還元します。その貢献内容は、単純な誤字修正やサンプルの追加から、他のAPI（例：Eコマースプラットフォーム）との連携例の紹介までさまざまです。また、開発者自身がPostmanノートブックを作成・公開し、APIの使い方を解説するケースもあります。これにより、他の開発者がすぐに実行・学習できる、実践的でインタラクティブな学習リソースが生まれます。