Postmanとは：APIテストとリクエストの扱い方

Postmanとは何かと主な機能

Postman はAPIの開発とテストのためのプラットフォームで、デスクトップアプリ（Windows、macOS、Linux）とウェブ版で利用できます。2012年にChrome拡張機能として誕生したPostmanは、モニタリング、モックサーバー、クライアントコード生成をサポートする本格的なエコシステムへと成長しました。

リクエストとレスポンスの形式

PostmanはすべてのHTTPメソッド（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）に対応しています。リクエストボディはJSON、XML、form-data、x-www-form-urlencoded、binary形式を使用できます。レスポンスはシンタックスハイライト、Pretty-print、生のヘッダー表示に対応しています。

認証サポート

組み込みの認証タイプには、Bearer Token、Basic Auth、Digest Auth、OAuth 1.0、OAuth 2.0、API Key、AWS Signatureがあります。Postmanは選択したタイプに応じてAuthorizationヘッダーを自動的に追加するため、トークンを手動でコピーせずに保護されたエンドポイントのテストを高速化できます。

Postmanのインターフェースとナビゲーション

Postmanのインターフェースは、サイドパネル（Collections、APIs、Environments）、ワークエリア（Request Builder/Response Viewer）、下部パネル（Console、Runner）で構成されています。ParamsタブではURLのクエリパラメータをテーブル表示で編集でき、HeadersタブではHTTPヘッダーを管理できます。

Postman Console

Console（View → Show Postman Console）は、中間リダイレクトやヘッダーを含むすべてのネットワークリクエストとレスポンスを時系列で記録します。標準のResponse Viewerが最終結果のみを表示する場合、複雑なOAuthフローやリダイレクトチェーンのデバッグには欠かせないツールです。

Workspacesとチーム作業

PostmanはForkとMergeによるコレクションのバージョン管理を備えたチームワークスペースをサポートします。チームメンバーはリクエストにコメントし、変更を提案し、コレクションをリアルタイムで同期できます。Public Workspaceを使用すると、外部の開発者向けにAPIドキュメントを公開できます。

HTTPリクエストの作成と送信

Postmanでの基本リクエストは、HTTPメソッドを選択し、アドレスバーにURLを入力して作成します。送信後、レスポンスはステータスコード、実行時間、サイズとともに下部パネルに表示されます。リクエストパラメータは入力時に自動的にエンコードされます。

動的変数とスニペット

URLとリクエストボディでは、{{$variable}}形式の動的変数を使用できます。組み込み変数の{{$guid}}、{{$timestamp}}、{{$randomInt}}は、各リクエストに対して一意の値を生成します。コードスニペットはCodeボタン（）から利用でき、cURL、Python、JavaScript、Kotlin、Swiftなどの言語で同等のリクエストを生成します。

// Pre-requestのスクリプト例：HMAC署名の生成
const timestamp = Date.now().toString();
const secret = pm.environment.get("api_secret");
const hash = CryptoJS.HmacSHA256(timestamp, secret);
pm.request.headers.add({
    key: "X-Signature",
    value: hash.toString()
});

コレクションと環境変数

コレクションとは、プロジェクトや機能モジュールごとにまとめた関連リクエストのグループです。各コレクションには、ネストしたフォルダ、共通ヘッダー、コレクション内の各リクエストの前に実行されるPre-requestスクリプトを含めることができます。リクエストの順序はドラッグで設定します。

環境変数とグローバル変数

Postmanは変数の5つのレベルをサポートします：global、collection、environment、data、local。競合解決の優先順位はローカルからグローバルの順です。環境ファイルには、development、staging、productionなど異なる環境用のキーと値のペアが含まれます。環境を切り替えると、すべてのURLとトークンが自動的に変わります。

スクリプトによるAPIテストの自動化

Postmanでは、レスポンス受信後に実行されるTestsタブにJavaScriptでテストを記述できます。テストはステータスコード、レスポンスボディ、ヘッダー、実行時間を検証します。結果は色付きの合格インジケーターとともにTest Resultsパネルに表示されます。

pmライブラリとリクエストチェーン

pmオブジェクトは、レスポンスを扱うメソッドを提供します：pm.response、pm.expect、pm.variables。リクエストチェーンは、あるリクエストのレスポンスからデータを変数に保存し、次のリクエストで使用することで実現します。これは統合テストの構築と、一連のAPI呼び出しによるビジネスロジック検証の基盤です。

// テスト：レスポンス構造の検証とトークンの保存
pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
});

const json = pm.response.json();
pm.environment.set("auth_token", json.data.token);

Collection RunnerとNewman

Collection Runnerは、コレクション内のすべてのリクエストを順番に実行し、各ステップでテストを実行します。NewmanはCI/CDパイプライン（Jenkins、GitHub Actions、GitLab CI）用のPostmanのコンソール版です。Newmanはモニタリングシステムとの統合のためにJSON、JUnit、HTML形式でレポートをエクスポートします。

GraphQLとWebSocketの扱い方

PostmanでのGraphQLリクエストは、JSON形式のボディを持つ単一のエンドポイントへのPOSTで送信されます。GraphQL（Beta）タブは、シンタックスハイライト、フィールドの自動補完、スキーマを備えたビジュアルエディタを提供します。リクエスト変数は別のVariablesパネルで渡されます。

WebSocketとSocket.IOのテスト

Postmanは、メッセージパネルを備えた専用インターフェースでWebSocket接続をサポートします。テキストおよびバイナリメッセージの送信、接続履歴の表示、切断時の自動再接続が可能です。Socket.IOクライアントはEngine.IOプロトコルとの互換モードで動作します。

// pm APIを使用したPostmanのWebSocketテスト
const ws = new WebSocket("wss://echo.websocket.org");
ws.onmessage = (event) => {
    pm.test("Echo response received", () => {
        pm.expect(event.data).to.eql("Hello");
    });
};

Postmanのモックサーバーとモニタリング

Postmanのモックサーバーは、既存のコレクションに基づいてAPIエンドポイントをエミュレートできます。バックエンドがまだ準備できていない一方で、フロントエンドやモバイルアプリがすでに開発されている場合に便利です。モックサーバーは、正しいヘッダーとステータスコードでコレクションのサンプルレスポンスを返します。

モックサーバーの作成

モックサーバーはコレクションからワンクリックで作成できます：コレクションを選択 → Mock Servers → Add a new mock server。Postmanは一意のURLを生成し、実際のAPIの代わりにアプリケーションコードで使用できます。コレクションの各リクエストに対して、モックは保存されたExample Responseを返し、バックエンドの完了前にUIをテストできます。

Postman MonitorsによるAPIモニタリング

Monitorsはコレクションをスケジュールに従って実行し（5分ごと、1時間ごと、1日ごと）、APIの可用性と正確性をチェックします。テストが失敗すると、モニターはメールまたはSlackに通知を送信します。モニタリングはPostmanのクラウドで動作し、専用サーバーは不要で、無料プランでは月間最大10,000リクエストをサポートします。

// モニタリング用テスト：応答時間の検証
pm.test("Response time < 2000ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

pm.test("Content-Type is JSON", () => {
    pm.response.to.have.header("Content-Type");
});

セキュリティとシークレット管理

Postmanは、APIキーを安全に扱うためのメカニズムを提供します。Secretタイプの変数は暗号化され、インターフェースに表示されません。チーム作業には、Admin、Editor、Viewerのロールを持つWorkspaceを使用してください。

変数の暗号化

環境変数を作成する際は、Secretタイプを選択すると、すべてのインターフェースで値がアスタリスクで隠されます。シークレットは共有時にコレクションにエクスポートされず、Newmanログにも表示されません。パスワードとトークンはSecret変数のみに保存することをお勧めします。

Vaultとの統合

PostmanはHashiCorp VaultとAWS Secrets Managerとの統合をサポートします。Pre-requestスクリプトは外部ストレージからシークレットを動的に取得でき、コレクションの環境ファイルに機密データを保存することを回避します。

セキュリティとシークレット管理

Postmanは、APIキーを安全に扱うためのメカニズムを提供します。Secretタイプの変数は暗号化され、インターフェースに表示されません。チーム作業には、Admin、Editor、Viewerのロールを持つWorkspaceを使用してください。

変数の暗号化

環境変数を作成する際は、Secretタイプを選択すると、すべてのインターフェースで値がアスタリスクで隠されます。シークレットは共有時にコレクションにエクスポートされず、Newmanログにも表示されません。パスワードとトークンはSecret変数のみに保存することをお勧めします。

Vaultとの統合

PostmanはHashiCorp VaultとAWS Secrets Managerとの統合をサポートします。Pre-requestスクリプトは外部ストレージからシークレットを動的に取得でき、コレクションの環境ファイルに機密データを保存することを回避します。