Postman の環境を整備し開発のしやすさをちょっと上げた話

はじめに

デリッシュキッチン開発部のバックエンド中心で開発をしている@きょーです。

この記事では、普段業務で Postman を使っていく際に便利だと思った機能について紹介します。

Postman とは

Postman は、API の構築・利用を支援する API プラットフォームです。API リクエストの作成・保存、リクエスト送信後のレスポンス確認といった用途で利用されることが多いですが、他にも様々な機能があります。

Postman で開発効率を上げるための便利機能

変数

変数を使う前後の差分を先に示します。

変数を設定・使用することで同じ値として使い回されることが多い URL のドメイン部分や Header の情報などを一箇所で管理できるようになります。

また、開発環境や本番環境用の変数を設定することで簡単にリクエストの向き先を変えることもできます。

Postman の変数にもスコープという概念が存在し、広いものから順に、Global、Collection、Environment、Data、Local となっています。上記で紹介した環境ごとの変数は Environment 変数になります

Postman における Collection と Environment の違いが分かりずらいので補足です。 Collection は API リクエストをグループ化するための機能で使われ、Environment はグルーピングされたリクエスト群に対して環境を変えるために使われることが多い認識です。

learning.postman.com

ここで実際に使われることが多かった 3 つの変数の特徴と実際の使用例について紹介しようと思います。

Global 変数
- 特徴
  - Postman 全体で有効な変数
  - どのコレクションやリクエストからも参照可能で環境に依存しない値を保持するのに適している
- 実際の使用例
  - 複数コレクション（=システム）で共有する認証情報
Collection 変数
- 特徴
  - 特定のコレクション内でのみ有効な変数
  - コレクション内のリクエスト間で値を共有するのに適している
- 実際の使用例
  - 環境を問わないリクエストパラメータ
  - device や os のバージョン
Environment 変数
- 特徴
  - 特定の環境 (開発環境、テスト環境、本番環境など) のみで有効な変数
  - API の domain 部分や認証情報などの環境ごとに異なる値を設定するのに適している
- 実際の使用例
  - API の domain 部分
  - 認証情報

詳しい説明は公式ドキュメントをご覧ください。

script

Postman では、リクエストの前後に JavaScript のコードを実行できます。

これらはそれぞれpre-request script、post-response scriptと呼ばれるもので、実行順序は以下の画像のようになっています。

試しに前のセクションで設定した環境変数であるX-Foods-Tokenを自動で更新する script を書いてみましょう。手順は以下の通りです。

X-Foods-Tokenに設定される値を取得（リクエスト先：/signup）
レスポンスから token を抽出
抽出した token をX-Foods-Tokenに設定

X-Foods-Token を自動で更新する post-response script

以下のようにpmオブジェクトを通して Postman が提供している機能を使用することができます。

const response = pm.response.json();
pm.environment.set("X-Foods-Token", response.token);

他にもリクエスト URL、Header、リクエストパラメータなどを動的に生成・変更したり、テストデータを準備するために外部ファイルから読み込むことなどもできます。

また、一つのリクエストだけでなく Collection に対して script を設定することもできるみたいです。Collection 全体で実行したい処理がある場合にはとても便利な機能です。

詳しい説明は公式ドキュメントをご覧ください。

Postman へのインポート機能

Postman では cURL 形式のリクエストや OpenAPI 仕様で作成されたドキュメント等の取り込み・管理ができます。

管理できるようになることで簡単に API リクエストの保存・リクエストパラメータの変更ができるようになります。

それでは実際に二つの形式で取り込んでみましょう。

cURL

curl --location --request GET 'http:/localhost:8080/foods' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Foods-Token: foods-token' \

上記のリクエストをエンドポイントを書く場所にコピペしてみましょう。

正常に import できると下の画像のように cURL リクエストを Postman に取り込むことができます。リクエスト先、ヘッダー、リクエストパラメータがすべて取り込まれていることがわかります。

同じように書き出し Postman で管理されてあるリクエストを cURL 形式で書き出したり Go や Rust での書き出しもできるようでした。

OpenAPI 仕様書

sample ファイルはこちらのものを使います。

yaml ファイルを Postman の上にドラッグドロップすると import ができるので、そのまま import を続行してください。

正常に import できると下の画像のように OpenAPI 仕様書を Postman に取り込むことができるかと思います。

最後に

今回は Postman についての Tips について紹介させていただきました。

これらの整備をしたから最高に開発しやすくなる！！みたいなことはないと思いますが、普段の業務の 1% くらいは開発しやすくできたのではないでしょうか？この記事が皆様のお役に立てたなら幸いです！

参考

https://www.postman.com/

PS

Postman のテーマを変えられるので自分の色に染めたっていい！！

小学生の頃にハマったゲームの一つにパタポンというものがあります。単純なリズムゲーではあるのですが、キャラクターデザインやサウンドトラック、ゲーム性など色々なポイントが当時の自分に刺さりまくり ~~時間を溶かした~~ 楽しませてもらった作品です。なんとこの度、完全なる続編ではないのですが手掛けたクリエイターによる新作が今年リリースされるということで震えが止まりません！！

♪ ラッタ！ラッタ！ラッタッタ！

kickstarter.ratatan.jp

every Tech Blog

株式会社エブリーのTech Blogです。