Postman Flows のユースケースを自社 API を例に考えてみた

はじめに
Postman Flows
ユースケース
- PHONE APPLI API を例にすると？
所感
おわりに

はじめに

こんにちは、リサーチデベロップメントの後藤です。

先日チームに API のコレクションを共有する用途で Postman を久しぶりに使用しました。
VS Code の拡張機能である Thunder Client に出会ってからは、HTTP クライアントはもっぱらこちらを利用していたのですが、久しぶりに Postman を開いたら、なにやら見知らぬ機能（タブ）、Flows が追加されていました。

今回はこの Postman Flows を触ってみた所感やユースケースの例を記事にしてみました。
ぜひご覧ください。

Postman Flows

learning.postman.com

Postman Flows とは API ワークフローを作成するためのビジュアルツールです。
見た目も含め、Node-RED に使用感が近いな感じました。

ブロックと呼ばれる処理を繋げることで一連のフローを構成できるようになっています。
ブロックは大きく3種類あり、用途によって使い分けることができるようです。

Task blocks：特定の非同期タスクを実行
Value blocks：特的のデータを作成
Operation blocks：データに対してアクションを実行して、データを変換

ユースケース

では Postman Flows は一体どのようなシーンで活用できるのでしょうか？
公式では以下のように説明されています。

A very common use case is to take data from once response, and pipe that to another request. Let's consider an example where want to create a post and then want to use the id of that post in the next request to update it.

【翻訳】

非常に一般的なユースケースは、1回の応答からデータを取得し、それを別の要求にパイプすることです。投稿を作成し、次のリクエストでその投稿のIDを使用して更新する例を考えてみましょう。

つまり、ある API のリクエストに必要な値を別の API から取得する必要がある場合に、この Postman Flows が利用できるということですね。

その他にも、以下のようなシナリオが想定されているようです。

	シナリオ	解決策
1	相互には依存しないが、特定の順番で API のリクエストを行う必要がある場合	signal という接続方法でブロックを繋げることで実行される順番が担保される
2	アクセストークンによる認証が必要なリクエストを複数回実行する場合	durables と呼ばれる、いわゆるフロー内変数にアクセストークンを保持しておくことができる

今回は、"1回の応答からデータを取得し、それを別の要求にパイプする" シナリオのフローを、弊社の PHONE APPLI API を例にして考えてみました。
使用するリソースは以下の2つです。

	API name	path
1	社内連絡先一覧取得	GET /users
2	社内連絡先取得	GET /users/{userId}

※ 以下がPHONE APPLI API のドキュメントです。ご興味あるかたはぜひ御覧ください。

developer.phoneappli.net

今回のシナリオでは、社内連絡先取得 API をテストすること、をゴールと考えます。

PHONE APPLI API を例にすると？

さて、この社内連絡先取得 API ですが、Path Parameters に userId という値を必須で指定することになっています。
userId は社員番号とは異なり、システム内で社内ユーザを一意に特定するための値となっているため、一般の利用者から見たらそれほど馴染み深い値ではないと思います。
そのため、出来れば userId よりも馴染み深い値、メールアドレスや社員番号などで社内連絡先取得 API をテストできると良さそうです。

社内連絡先一覧取得 API を利用すると、メールアドレスなどで社員を検索することができ、Response として userId を取得することが可能です。そのため、この API を間に挟むことで上記のような userId 問題に上手く対応できそうです。

以下に社内連絡先一覧取得 API のサンプルを記載します。

Request samples

curl --location --request GET 'https://api.phoneappli.net/v1/users?email1=dummy@example.com' \
--header 'X-Pa-Api-Key: { VALUE }'

Response samples (一部省略）

{
    "hasMore": false,
    "items": [
        {
            "userId": 0,
            "fullname": "string",
            "fullnameKana": "string",
            "employeeNum": "string",
            "divisions": [
                {
                    "divisionId": 0,
                    "divisionName": "string"
                }
            ],
            "position": "string",
            "extensionNum": "string",
            "companyMobileNum": "string",
            "personalMobileNum": "string",
            "phoneNum": "string",
            "mobileNum": "string",
            "faxNum": "string",
            "email1": "string",
            "email2": "string"
        }
    ]
}

　シナリオを Postman Flows で表現

ここまでのシナリオをPostman Flows で実際に表現してみます。
以下が実行の流れです。

メールアドレスを Query Params に含め、社内連絡先一覧取得 API を実行する
返ってきた値（社員）が1人だった場合、その userId を Path Parameters に含め、社内連絡先取得 API を叩く

先頭に String block を配置しメールアドレスを、次の Send Request block (社内連絡先一覧取得 API ) に渡します。
Condition block でステータスコードとマッチした社員数を確認し、チェックが通れば userId を、2つ目の Send Request block (社内連絡先取得 API) の Path Parameters として渡します。

今回のフローでは、それぞれの API で出力をグループ分けしているため、Terminal からは以下のように見え、結果が確認しやすくなっています。

所感

実際に使ってみて、良かったところ は
"Postman のコレクションをそのまま流用できるところ"だと感じました。

これまで Postman で使用していたリソースを、そのままワークフローの1ブロックとして扱える点はとてもいいなと思いました。
下図のように Send Request は、既存のコレクションから選択することができるようになっており、やりたいことがスムーズにできている感じがあって、個人的には素敵な体験だなと思いました。

他にも魅力は多々あると思いますが、この点は Postman Flows を使う理由に十分なるのではないかと感じます。