POSTMAN BEST PRACTICES
Flows
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は、APIを構築するエンジニアから、そのAPIを連携するパートナーまで、チームに関わるすべての人が、分散したドキュメントを探したり、ワークフローの作成者に確認したりすることなく、APIワークフローの流れを確認し、実行できることが重要だと考えています。
この章では、Flowsを使って複雑なAPIワークフローを、実際に操作・実行でき、共有も可能な形にする方法を紹介します。また、ドキュメント、テスト、共同作業、オンボーディングのほか、AIエージェントが安定して利用できるAPIの構築にFlowsを活用する方法についても説明します。
Abhinav Asthana
Postman CEO and Co-founder
Ankit Sobti
Postman Field CTO and Co-founder
API開発では、エンドポイントを構築して保守するだけでは十分ではありません。現在のAPI利用者には、開発者、テスター、パートナー、AIエージェントなどが含まれます。こうした利用者が必要なAPIを見つけ、その仕組みを理解し、確実に連携できることが重要です。Flowsは、これを実現するために設計されています。
Flowsはコレクションを基盤としており、APIリクエストを順番に組み合わせたり、データを変換したり、条件に応じて処理が変わるワークフローを視覚的に構築して実行できる環境を提供します。
Flowsの主な機能
| 機能 | 説明 | できること |
|---|---|---|
| 無限キャンバス | APIワークフローを自由な広さで設計・可視化できるワークスペース | 固定された表示領域やレイアウトに制約されることなく、複雑なワークフローを自由に配置、拡大・縮小しながら確認できます。単純なリクエストの連携から、多数のステップで構成される大規模なシステムまで、1つの共有キャンバス上で表現できます。 |
| モジュール化されたFlows | 複数のFlowsで共有して再利用できるワークフローロジックです。同じスクリプトを複製したり、それぞれを個別に管理したりする必要がありません。 | ワークフロー間で一貫性を保ちやすくなります。また、APIの変更に伴って共通のロジックを更新する際も、複数のワークフローを個別に修正する手間を減らせます。 |
| グループ化と整理 | ワークフローのロジックを順を追って理解できるよう、説明を加えてキャンバスを整理する機能 | 新しいチームメンバーのオンボーディングや、パートナーへのワークフローの説明を分かりやすくし、必要な時間を短縮できます。 |
| ライブ埋め込み | ワークフローを視覚的に表現し、社内外のドキュメントで共有したり、直接埋め込んだりできる機能 | API利用者はドキュメントを離れることなく、APIがどのように連携しているかを最新の状態で正確に確認できます。 |
| テストシナリオ | ワークフローを個別に用意することなく、さまざまな入力値を定義してテストできる機能 | 環境変数の値を直接使用して、さまざまな条件での動作を検証し、エッジケースもテストできます。 |
| 実行ログ | 視覚的なワークフローをステップごとに実行・追跡し、各段階の入力、出力、状態を確認できる機能 | エラーのデバッグや動作の検証がしやすくなり、ワークフロー内でデータがどのように受け渡されているかを把握できます。 |
ドキュメントでのFlowsの活用
個々のAPIコールについて説明するだけでは、APIを使った一連の処理の全体像までは十分に伝わりません。実際の課題を解決するには、複数のエンドポイントがどのように連携して動くのかを開発者が理解する必要がありますが、文章だけのドキュメントでそれを分かりやすく伝えるのは困難です。Flowsを使えば、ドキュメントを実際に実行して操作できるワークフローとして提供し、誰でもその動きを確認できます。
グループ化と整理を使って、キャンバスの各セクションに説明を加えて構成を整理します。これにより、システムに詳しくない人でも、ワークフローのロジックを順を追って理解できるようになります。
Flowが完成したら、ライブ埋め込みを使って、そのワークフローを既存のドキュメント内に表示できます。ドキュメントのページにFlowを直接埋め込むことで、文章による説明とあわせて、実際に実行できるワークフローを確認してもらえます。Postman API NetworkでパブリックAPIを公開している場合は、Public API NetworkのページにもFlowを埋め込めます。APIを初めて見つけた開発者も、エンドポイントの情報を見るだけでなく、APIが実際にどのように連携して動くのかをすぐに確認できます。
APIテストでのFlowsの活用
Postmanでは、コレクションランナーを使ったコレクションベースのテストと、Flowsを使った視覚的なワークフローテストという2つの方法でAPIをテストできます。条件分岐が必要なテストや、複数のステップからなる一連の処理を視覚的に確認したい場合は、Flowsが適しています。また、スクリプトを書かずにテストを作成、レビュー、変更できるため、技術的な知識が少ないメンバーも参加するチームに適しています。
複雑なエンドツーエンドのシナリオをテストする場合は、組み込みのブロックを使ってAPIレスポンスに応じた条件分岐を設定します。さらに、テストシナリオを使えば、入力値ごとに別のワークフローを用意することなく、さまざまな入力に対する動作を検証できます。特に、返されたデータによってAPIコールの順序が変わるような場合に、Flowsを使うことでワークフロー全体のロジックを効果的に検証できます。
テストにAIを取り入れるには、Agentブロックを使ってワークフローのロジックを柔軟にしたり、Agent Modeを使ってテスト用のFlowsを自動生成したりできます。Agent Modeで対象のコレクションを指定すると、実行してイテレーションを重ねられるワークフローが自動的に作成されます。
CI/CDパイプラインの一部としてFlowsを実行する方法は2つあります。Enterpriseライセンスがある場合は、Postman CLIを使ってFlowsを直接実行でき、プライベートネットワーク内のAPIに対して実行することもできます。Enterpriseライセンスがない場合は、デプロイ済みのFlowからリクエストを作成してコレクションに追加し、Postman CLIを使ってコレクションランナーから実行できます。
AIが利用しやすいAPIでのFlowsの活用
AIエージェントやLLMがAPIを安定して利用するには、人間の開発者とは異なる要件があります。一貫した命名規則、予測しやすいレスポンススキーマ、適切に構造化されたエラー処理が必要です。これらが整っていないと、エージェントがレスポンスを誤って解釈したり、エラーに気づかないまま処理を続けたりする可能性があります。Flowsを使えば、既存のエンドポイントを変更することなく、APIの入出力をFlowsで調整して、こうした要件を満たすことができます。
具体的には、Flowsを使って次のことができます。
- レスポンス全体の構造を統一し、たとえばデータを常に一定の形式の
dataフィールドに格納するなど、すべてのレスポンスを一貫した形式にします。 - 日付、ブール値、数値の識別子などが常に期待する形式で返されるように、データの型を変換します。
- エージェントにレスポンスを渡す前に、不要なフィールドや一貫性のない部分を除外したり、フィールドの対応関係を変更したりします。
- 複雑にネストされたデータ構造をフラット化し、エージェントが階層をたどってデータを探す必要をなくします。
- nullの扱いを統一します。たとえば、空のコレクションではnullやフィールドの省略ではなく、常に空の配列を返すようにします
これにより、エージェントやユーザーがAPIをどのように利用するかをコントロールし、エンドポイントの呼び出し方と返されるレスポンスの形式を整えることができます。
FlowsでAPIを必要な形に整えたら、FlowをMCPサーバーとしてデプロイできます。これにより、ワークフローをLLMが直接呼び出せる構造化されたインターフェースとして提供できます。既存のインフラストラクチャを変更することなく、AIエージェントからAPIを利用できるようになります。
共同作業でのFlowsの活用
APIの共同作業では通常、コレクションやAPI仕様、ドキュメントへのリンクを共有しますが、それだけでは個々のエンドポイントがどのように連携して動くのかをAPI利用者自身が理解する必要があります。Flowsを使えば、チームで整備したコレクションとあわせて、一連の業務プロセス全体を1つの実行可能なワークフローとして示すことができます。社内ワークスペースで共同作業する場合も、パブリックワークスペースやPartner Workspaceを通じて社外と共有する場合も、関係者はAPIがどのように連携するのかを分かりやすく確認し、そのまま実行できます。ワークフローの構成について疑問があれば、ドキュメントを探さなくても、Agent Modeに自然言語で質問して回答を得られます。
PostmanのLocal viewを使えば、FlowsをAPIのコードと一緒にバージョン管理することもできます。クラウド上のFlowsをGitと同期したローカルフォルダーに取り込み、PostmanのUIからでも、IDEでAIを活用する場合でも、コードベースとあわせて最新の状態に保てます。チームメンバーがリポジトリをクローンすれば、適切なワークスペースを探すことなく、すぐにFlowsを実行できます。
オンボーディングでのFlowsの活用
Flowsでは、APIワークフローを実際に実行しながら確認できるため、新しいチームメンバーが初めて触れるシステムを理解するまでの時間を短縮できます。文章だけのドキュメントを読む代わりに、開発者はFlowを開いて実行し、APIコールの順序や、その間でデータがどのように受け渡されるかをすぐに確認できます。
グループ化と整理を使ってキャンバスに説明を加え、構成を整理することで、ワークフローをシステムの仕組みを順を追って学べるガイドとして活用できます。テストシナリオも用意しておけば、新しい開発者がエッジケースやエラー発生時の動作を安全に試すことができます。テストシナリオはPostmanの環境やVaultと直接連携するため、本番データに影響を与えることなく、開発環境やステージング環境で実行できます。
さらにAgent Modeを使えば、開発者はどのFlowについても自然言語で質問できます。特定のステップで何をしているのか、ブロック間でデータがどのように受け渡されるのか、なぜ特定の処理経路を通るのかなどを質問し、別のドキュメントを探して読み解くことなく、その場で回答を得られます。
Flowsのはじめ方
- 新しいFlowを作成：Postmanワークスペースのサイドバーから［Flows］を選択する。［+］ボタンまたは［Create Flow］をクリックすると、［Start］ブロックがあらかじめ配置された新しい空のキャンバスが開く。
- 最初のブロックを追加：キャンバス上の任意の場所を右クリックしてブロックを追加する。最初のステップとして、既存のコレクションからリクエストを追加するのが一般的である。
- ブロックを接続：ブロックの右側にある出力ポートにカーソルを合わせ、接続線を次のブロックの左側にある入力ポートまでドラッグして、処理の流れを作成する。
- Flowを実行：キャンバス下部の［Run］ボタンをクリックする。Flowが実行され、処理が進むにつれて各ブロックの下にリアルタイムのデータが表示される。実行内容を詳しく確認するには、［Run］パネルを開く。各ステップの実行内容を順番に確認できるほか、検索可能なコンソールの生ログも確認できる。
主な成果
このガイドで紹介した方法を実践することで、次の3つの重要な成果が得られます。
- オンボーディングの短縮と繰り返しの質問を削減：ワークフローを見てすぐに実行できるようにすることで、新しいチームメンバーやパートナーが仕組みを理解しやすくなります。分からないことがあるたびに、ワークフローの作成者に確認する必要も減らせます。
- AIが安定して利用できる一貫したAPI：FlowsをAPIとの間に入るアダプターとして使うことで、AIエージェントに渡す情報やレスポンスの形式を調整し、一貫した動作を実現できます。
- APIの変更に合わせて更新されるドキュメント：Flowsをコードと一緒にバージョン管理し、ドキュメントに埋め込むことで、APIの変更に合わせてドキュメントも最新の状態に保てます。
使いながら理解するのが一番です。Postman Flowsについて詳しくはこちら →