API開発サービス「Postman」の推し便利機能

みなさん、API作ってますか？ポストマン使ってますか？

今回の記事担当こむです。前回の担当者たつきんの記事がPostmanについてでした（今更ながら初めてポストマン使ってみた。 - CrossMarketing Group Tech Blog）。ご存じの方も多いと思いますが、本当に使いやすいサービスで愛用しているので、好きな機能を中心に深掘りして紹介したいと思います。

リクエストの送信

Postmanのベースとなる機能です。GET、POST、PUT、DELETEなどのHTTPリクエストの他、GraphQLやgRPCなどのリクエストにも対応しています。

今回は、こちらも愛用の記事投稿プラットフォーム「note.com」の非公式API（ドキュメント等ありません）を例にします。こちらのAPIは認証不要で、該当APIのURLにアクセスするだけでレスポンスが取得できます。Postmanでは、リクエストを作成し、APIのURLを貼り付けてSendをクリックするだけです。

基本的なリクエスト

※note-API（非公式）で記事情報の取得｜KIYO の記事を参考にさせて頂きました。

postman-01-basic

パラメータつきのリクエスト

次にパラメータが必要なAPIとして、ユーザーの記事一覧を取得するAPIにリクエストを送ります。こちらもGETメソッドなので、必要な各パラメータはQuery Params欄に入力します。また、クエリストリングを含むURLが分かっている場合は、URLを貼り付けると自動的にQuery Params欄に値がセットされます（スマート！）

（POSTメソッドで送る場合は、パラメータはBodyタブのform-dataとしてセットすることが多いので注意）

Sendボタンを押すと、レスポンスが返り、指定ユーザーの記事一覧が含まれるのが分かります。

postman-02-params

パス変数

今回のURLには、クエリストリング以外にも、パスの一部に「kiyo_ai_note」という可変なユーザー名の値が含まれています。こういったパス中の値を変更したい場合、Path Variablesが便利です。使い方は、URLの該当の箇所を :urlname のように先頭コロンにすると、その部分を変数として下のPath Variables欄で設定できるようになります。

postman-03-pathparam

環境（変数）

主な変数としてこの他に、Environments（環境）というものがあります。こちらはAPI単位ではなく、ワークスペース内の全APIに作用させたい値を指定します。例えば、一般的に環境ごとに異なる base_url を設定しておいて、リクエストを送る際に切り替えて実行することが可能です。Environmentで設定した名前はURLの一部やパラメータの値として {{base_url}} のように記述できます。今回の例では「本番」などの環境名に base_url を https://note.com/api/v2 として定義して、URLの該当部分を {{base_url}} に置き換えました。

postman-04-envsetting

postman-04-env

基本的なリクエスト送信は以上です。各種変数が使えて既に十分便利ですが、Postmanには他にも優れた機能があるので、更に紹介いたします。

レスポンスの保存

リクエスト送信結果にある「Save as Example」ボタンで、結果に名前をつけて保存しておくことができます。保存したレスポンスは実際にリクエストを送ることなく確認できるため、代表的なパターンを保存しておくと便利です。パターン違いや、ステータスコード違いなどで保存したりします。

環境の同期

Postmanの利用にはアカウントが必要ですが、設定は全てアカウントに紐付いてクラウドに保存されます。普段と違う端末で利用したいなどの場合でも、特に移行などせずに保存してある設定を利用できます。

認証機能

今回紹介したnote.comのAPIと異なり、一般的にはAPIには認証が必要なことがほとんどです。PostmanはAPI KeyやBearer Token、Basic認証などの主要な認証機構に対応しているため、大抵のAPIにリクエストを送信できます。

ステートフルなAPI（ログインしているとリクエストできるAPI）を実装しているような場合でも、クッキーを設定することでリクエストが可能です。

コレクション

Postmanのリクエストはコレクション単位で管理します。イメージとしてはディレクトリのようなもので、複数のリクエストをグループ化することができます。コレクションの中にコレクションをネストすることができるため、階層化された整理も可能です。

そのほか、コレクション単位で以下のような機能をもっています。

コレクション単位の変数
コレクション単位の認証設定

ドキュメント

設定した内容はAPIドキュメントとしても利用できます。特に設定等は必要なく、コレクションとリクエストがあれば、右側にあるDocumentation→View complete collection documentationでドキュメントとして閲覧可能です。

postman-05-to-doc1

postman-05-to-doc2

各API自体や各パラメータのdescriptionを記述することで、詳細なドキュメントが完成していきます。ちなみにドキュメントはルート階層のコレクション単位で作成されるので、一つのドキュメントにしたい単位でルートコレクションを作成するというのが整理のヒントになると思います。

postman-06-doc

Publishという機能もあり、外部向けのAPIなどは、ボタン一つで全世界にAPIドキュメントを公開することができます。

チームでの共同作業

Postmanはチームでの作業にも便利です。作成したコレクションや環境をチームメンバーと意図的に共有したり、共有中されたアイテムは個人の作業と同様にリアルタイムで変更が反映されます。エクスポートとインポート機能で共有は可能ですが、共有機能を利用すると手間なく同一の設定を共有することが可能になります。（プランにより人数など制限あり）

自動化テストとCI/CDとの連携

これはまだ使ったことがないですが、PostmanはAPIの動作を自動的にテストする機能も提供します。これらのテストをCI/CDパイプラインに組み込むことも可能なようです…

まとめ

以上、Postmanの主な機能（の一部）を紹介しました。いかがでしたでしょうか。

今のシステム開発は色々なところでAPIを介したデータの受け渡しを行うので、もし使ったことがない方いれば、ぜひ活用してみてください！