Postman ってなに

https://www.getpostman.com/products
一言で言うとリッチなユーザインターフェイスを搭載している HTTP クライアントです。

HTTP クライアントというと、例えば curl は皆さん1度は使ったことがあるであろうお馴染みですが、
特に API のテストや開発フェーズにおいて、ダイナミックなパラメーターを持つ多くのエンドポイントを行ったり来たりする際には、CLI よりも Postman のようなリッチな HTTP クライアントが便利なケースがあります。

また、最近では単なる HTTP クライアントとしての役割を超えて、

Postman Collections
Workspaces
API Mock server
Automated tests
Monitoring
Documentation

などの機能を備え、API 開発を行う上での統合開発環境を目指しており、Postman 自身も "The Only Complete API Development Environment (ADE)" と表現しています。

Postman Client の基本について

基本的な部分については色々な方々が紹介されているので、下記などをご参考に確認いただけると。

Postman Collections を使う (& 外部公開する)

今回は先に紹介した色々な Postman の機能の中でも、最も基本的かつすぐに活用がしやすい Postman Collections についてです。上記に貼った Postman Client のスクリーンショットで、左ペインに見えるフォルダ構造になっている部分、ここがいわゆる Collections です。

この例だと、3つの Collections が存在していて、それぞれにいくつの API (endpoint) が含まれているのかが分かります。Collections はフォルダを作るのと同じ要領で自分で好きに追加・管理することができ、いわゆる API の雛形を登録しておくことができます。

これによって、毎回 API のドキュメントページを見に行って、パスをコピーしてパラメーターをコピーして、、、みたいな作業をすることなく、Postman を開くだけですぐに必要な API を実行することができるようになります。
Collections では URI や Query parameters に変数 variables を使えるので、例えば URI パスに含まれるアカウントID やバージョン番号など、任意の部分は全て変数として登録しておくことで、一括管理・変更が可能になります。登録時にこれらを上手く使うことで Collections のメンテナンスを行う必要がなくなります。

そんな Collections ですが、色々な使い方があると思います。

自分用としての Collections

個人的に Postman を利用している場合、例えば頻繁に利用するサービスの API を Collections にポチポチ登録しておき、使いたい時にすぐに使えるようにしておく、といった使い方が最もイメージしやすいと思います。もちろんテストやモニタリングなど用途は人それぞれあると思います。

コラボレーション用としての Collections

チームとして Postman を使っているような場合、作成した Collections を共有することで全員が最新の Collections を使うことができます。

また特に自社サービスで外部の開発者に向けて API を公開しているような場合、Postman Collections を公開することで例えば:

自社のセールスエンジニアが API を気軽に使うことができるになる (営業先でのデモ)
API の公開ドキュメントに Postman Collections へのリンクを入れることで、一般開発者も Postman Collections を使って効率的に API を使った開発を進められる。

などのメリットが考えられます。
実は上記で貼ったスクリーンショットに含まれる3つの Collections は全て一般開発者向けに公開されている Postman Collections を import したものなのです。

API を使う開発者の立場になって考えると、公式にこういうツールが提供されるのはとても嬉しいですよね。

Collections を公開するには

Collections を公開する方法として大きく2つあります。1つ目は自分で作成した Collections をエクスポートして、生成される JSON ファイルを共有、GitHub などで公開する方法、2つ目は Postman の機能を使って Collections を外部に公開し、誰でもアクセスができる共有用の URL を生成する方法です。

1. JSON ファイルを共有・公開する方法 (△)

対象の Collections を選択し、Export するだけです。

デメリットとして、Collections に何か新しい変更を加えた場合、再度ファイルを生成して共有・公開しないといけません。

2. Collections 用の共有リンクを発行する (◎)

もし作成した Collections を幅広いオーディエンスに向けて公開しようと考えている場合はこちらの方法の方がオススメです。

まず対象の Collections を選択し、Share Collection をクリックします。

次に Get link タブへ移動し、Get Link ボタンをクリックし、共有リンクを発行します。

正しく発行が終わると下記のように URL が表示されます。

この URL に直接アクセスすると、先程 1. の方法で生成した JSON ファイルと同じ内容が見えると思います。
つまりこの方法のメリットは、新しい変更を Push 型ではなく Pull 型でユーザーへ提供できる点でしょう。

注意点

この URL は一度発行されると、削除して再生成しない限り変わることはありません。
上記のスクリーンショットの Update Link は、URL を再生成するという意味ではなく、URL に紐づいている Collections の内容を最新のものに更新する、という意味です。

つまり何が言いたいかというと、URL が発行されると、この URL には "その時点" での Collection のスナップショットがコピーされ紐付けられます。リンクを発行後に Collection を更新しても、明示的にこの Update Link を実行しない限り変更は反映されません。分かりにくい。。。

`Run in Postman` ボタンを使う

これまで Collection を共有する方法を紹介してきました。URL での共有が可能なことが分かりましたが、これでは結局ユーザーが自分でファイルに保存して import という面倒なステップを踏むことになります。
Postman が提供している Embed 機能を使うと、Web ページ上に設置したボタンをユーザーが押すだけで当該 Collection をユーザーの Postman Client に直接 import でき、そうした煩わしさから解消されます。

※↓は実際に押せるボタンです。

例えば Twitter Ads API の API リファレンスページには各ページにこの Run in Postman ボタンが設定されていて、ユーザーがここからすぐに Collection を import することができるようになっています。
https://developer.twitter.com/en/docs/ads/analytics/api-reference/active-entities

ボタンの作り方

先程のように、対象の Collection から Share Collection をクリックし、今回は Embed タブを開きます。

先程のステップで既に共有リンクは生成してあるので、上記のように、HTML or Markdown 形式を選択するだけで、すぐに設置できる Run in Postman ボタンのコードスニペットが表示されます。これを自社のサイト上で使うことができます。ここでも Update Link ボタンの意味は先程説明した通りです。

Collection を公開・管理する上での注意点、その他

Workspace を分けた方がいい

Collection を作って上記の手順で一般公開した後、例えば誤って Collection を手元の Postman client から削除してしまった場合、公開されている Collection やリンクも跡形もなく闇に葬られてしまいます。
普段使いの Workspaceは汚れがちです。公開用の Collection を管理するためだけの神聖な Workspace を別途作っておいて、公開した Collection はそのクリーンな Workspace 内でのみメンテナンスするべきでしょう。

参考: Intro to Workspaces

Fork / Merge 機能を積極的に使う

外部公開用の Collection のメンテナンス時に誤った変更が混入してしまうと大変です。
Postman では git のような感覚で、既存の Collection からまず Fork されたコピーの Collection を作成し、そこに対して変更を適用、Merge 前にブラウザ上で変更一覧をグラフィカルに表示した上で最終的に Merge する、というフローを取ることが可能です。

参考: Version Control for Collections

Environment を上手く使う

序盤に説明しましたが、Collections では URI や Query parameters に変数 variables を使えるようになっています。Workspace 毎に設定可能な Environment には任意の変数を設定可能なので、ここに token などの認証情報はもちろん、URI に含まれる API のバージョン番号、アカウント ID などを変数として登録することで、Collection のメンテナンス性がグッと上がります。

参考: Intro to environments and globals

Collection データの更新は Postman API からも可能

これまでの例では全て Postman client を使って GUI 上から変更を加え、Collection を管理していくという方法についてでしたが、場合によってはとても手作業ではカバーできない量の変更が一度に必要になることがあるかもしれません (大量の文字列置換など)。
そういった場合に、1つのトリックとして、JSON 形式で export した Collection ファイルを使って一括変換を行い、それを POST body として Postman API から投げて、公開済み Collection の内容を GUI を経由することなくまるっと変更することができます。

参考: Postman API - Update Collection

Collection を複数人で共同管理するには有料プラン

Postman では作成した Workspace に他の人を invite して Collection を共同管理することができます。
ただし無料プランでは招待することができず、有料プランが必須となります。1人でやる分には一切課金なく、今回紹介した全ての作業を行えます。

一度 import した Collection を最新バージョンに "Update" する機能はない

公開された Collection を使うユーザー側の視点で考えます。管理者が新しい変更を加えて Collection を公開したとしても、Postman は特にアップデートの通知などをしてくれるわけではありません。ユーザーはもう一度 Collection を import する必要があります。

`Run in Postman` ボタンは、deep linking に対応していない

ボタンはとても便利ですが、特定のサブフォルダだけを import させる、といったことは出来ません。Collection 全体がインストールされます。また、ユーザーがボタンを押した際に既に Collection が import されているのかどうかを判断してくれないため、既に Collection を import 済みであっても毎回 import を問われます。

自社 API の Postman Collection を外部公開して社内外の開発者の生産性をあげていく