Postman入門｜APIテスト・開発を効率化するHTTPクライアント活用ガイド

API開発において、エンドポイントの動作確認やテストは欠かせない作業です。curlコマンドでもAPIのテストは可能ですが、リクエストの管理、環境ごとの変数切り替え、テストの自動化まで考えると、専用のツールを使うほうが圧倒的に効率的です。

本記事では、世界中の開発者に愛用されているHTTPクライアント「Postman」の基本的な使い方から、実務で活用できるテストの自動化テクニックまで、実践的に解説します。

Postmanとは？API開発に不可欠なツール

Postmanは、APIの開発、テスト、ドキュメント作成を支援するHTTPクライアントツールです。GUIベースの直感的なインターフェースで、GET、POST、PUT、DELETEなどあらゆるHTTPメソッドのリクエストを簡単に作成・送信できます。

Postmanが選ばれる理由

視覚的なインターフェース：curlコマンドの複雑なオプションを覚える必要がなく、GUIでヘッダー、ボディ、パラメーターを直感的に設定できます。

リクエストの保存と管理：APIリクエストをコレクションとして整理・保存でき、いつでも再実行可能です。

環境変数の活用：開発環境、ステージング環境、本番環境など、環境ごとにURL やトークンを切り替えられます。

テストの自動化：JavaScriptでテストスクリプトを記述し、レスポンスの検証を自動化できます。

チームでの共有：コレクションや環境設定をチームメンバーと共有し、API仕様の共通理解を維持できます。

インストールと初期設定

Postmanの公式サイト（postman.com）からデスクトップアプリをダウンロードしてインストールします。Windows、macOS、Linuxに対応しています。

アカウントの作成は無料で、基本的な機能はすべて無料プランで利用可能です。チームでのコラボレーション機能を使う場合は、有料プランの検討が必要になります。

Webブラウザ版も用意されているため、インストールせずにブラウザ上で使うことも可能です。ただし、ローカルサーバーへのリクエスト送信にはデスクトップアプリが必要です。

基本操作：リクエストの作成と送信

まずは、最も基本的なAPIリクエストの送信方法を確認しましょう。

GETリクエストの送信

新しいリクエストを作成するには、「New」ボタンまたはCtrl+Nで新しいタブを開きます。

手順

1. HTTPメソッドのドロップダウンから「GET」を選択します。

2. URL欄にエンドポイントのURLを入力します（例：https://jsonplaceholder.typicode.com/posts/1）。

3. 「Send」ボタンをクリックします。

レスポンスが下部のパネルに表示されます。Body、Headers、Test Results、Cookies などのタブで、レスポンスの詳細を確認できます。

クエリパラメーターの設定：「Params」タブで、キーと値のペアを設定できます。URLに直接?key=valueと入力しても構いませんが、Paramsタブを使うほうが見やすく、編集も容易です。

POSTリクエストの送信

データの作成や送信にはPOSTリクエストを使います。

手順

1. HTTPメソッドを「POST」に変更します。

2. URLを入力します（例：https://jsonplaceholder.typicode.com/posts）。

3. 「Body」タブを開き、「raw」を選択してフォーマットを「JSON」に設定します。

4. リクエストボディにJSONデータを入力します。

{
  "title": "サンプル記事",
  "body": "これはテスト投稿です",
  "userId": 1
}

5. 「Send」をクリックして送信します。

Bodyのフォーマットには、JSON以外にもform-data（ファイルアップロード時）、x-www-form-urlencoded（フォーム送信時）、raw（テキスト、XML等）があります。APIの仕様に合わせて適切なフォーマットを選択しましょう。

ヘッダーと認証の設定

多くのAPIではヘッダー情報や認証トークンが必要です。

ヘッダーの設定：「Headers」タブで、Content-Type: application/jsonやAccept: application/jsonなどのヘッダーを追加します。

認証の設定：「Authorization」タブでは、以下の認証方式を簡単に設定できます。

Bearer Token：JWTなどのトークンを入力するだけで、自動的にAuthorization: Bearer <token>ヘッダーが付与されます。

Basic Auth：ユーザー名とパスワードを入力すると、Base64エンコードされた認証ヘッダーが自動生成されます。

OAuth 2.0：OAuth 2.0のフローをGUIで設定し、アクセストークンの取得から利用までをPostman上で完結できます。

API Key：キーの名前と値、送信先（ヘッダーまたはクエリパラメーター）を指定できます。

コレクションでリクエストを整理する

コレクションは、関連するAPIリクエストをフォルダ構造でまとめて管理する機能です。プロジェクトやAPIの種類ごとにリクエストを整理できます。

コレクションの作成と構造化

左サイドバーの「Collections」で「New Collection」をクリックし、名前を付けて作成します。コレクション内にフォルダを作成し、階層的にリクエストを整理できます。

📁 ECサイトAPI
  📁 認証
    POST ログイン
    POST ログアウト
    POST トークンリフレッシュ
  📁 ユーザー
    GET ユーザー一覧
    GET ユーザー詳細
    POST ユーザー作成
    PUT ユーザー更新
    DELETE ユーザー削除
  📁 商品
    GET 商品一覧
    GET 商品検索
    POST 商品登録
  📁 注文
    GET 注文履歴
    POST 注文作成

コレクション全体に共通のヘッダーや認証設定を適用することもできます。コレクションの「Authorization」タブで設定した認証情報は、配下のすべてのリクエストに自動的に継承されます。

コレクションの共有とエクスポート

作成したコレクションはJSON形式でエクスポートし、チームメンバーと共有できます。Postmanのチームワークスペースを使えば、クラウド上でリアルタイムに共有することも可能です。

また、コレクションからAPIドキュメントを自動生成する機能もあります。リクエストの説明、パラメーターの解説、レスポンス例を記載しておけば、そのままAPI仕様書として公開できます。

環境変数とグローバル変数の活用

環境変数は、Postmanの最も強力な機能の一つです。開発環境と本番環境でURLやトークンを簡単に切り替えられます。

環境の作成と変数設定

右上の環境セレクターから「New Environment」で新しい環境を作成します。

# 開発環境
base_url: http://localhost:3000/api
auth_token: dev_token_xxxxx

# ステージング環境
base_url: https://staging-api.example.com/api
auth_token: stg_token_xxxxx

# 本番環境
base_url: https://api.example.com/api
auth_token: prod_token_xxxxx

リクエストのURLや設定で変数を参照するには、二重波括弧{{変数名}}を使用します。

GET {{base_url}}/users/1
Authorization: Bearer {{auth_token}}

環境をドロップダウンで切り替えるだけで、同じリクエスト定義で異なるサーバーにアクセスできます。

変数のスコープ

Postmanの変数にはいくつかのスコープがあり、優先順位があります。

Global変数：すべてのコレクション・環境で参照可能。共通の設定値に使用します。

Collection変数：特定のコレクション内でのみ有効。コレクション固有の設定に使用します。

Environment変数：選択中の環境でのみ有効。環境ごとに異なる値に使用します。

Data変数：Collection Runnerで外部データファイルから読み込まれる変数。

Local変数：スクリプト内で一時的に使用する変数。リクエスト間では引き継がれません。

テストスクリプトでレスポンスを自動検証

Postmanのテストスクリプト機能は、API開発の品質を大幅に向上させます。JavaScriptでテストコードを記述し、レスポンスの自動検証が可能です。

基本的なテストの書き方

リクエストの「Scripts」タブ（「Post-response」セクション）にJavaScriptでテストを記述します。

// ステータスコードの検証
pm.test("ステータスコードが200である", function () {
    pm.response.to.have.status(200);
});

// レスポンスタイムの検証
pm.test("レスポンスが500ms以内である", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// レスポンスボディの検証
pm.test("ユーザー名が正しい", function () {
    const jsonData = pm.response.json();
    pm.expect(jsonData.name).to.eql("田中太郎");
});

// Content-Typeの検証
pm.test("Content-TypeがJSONである", function () {
    pm.response.to.have.header("Content-Type", "application/json; charset=utf-8");
});

// 配列の検証
pm.test("ユーザー一覧が10件以上ある", function () {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.be.an("array");
    pm.expect(jsonData.length).to.be.above(10);
});

// JSONスキーマの検証
pm.test("レスポンスが正しいスキーマである", function () {
    const schema = {
        type: "object",
        required: ["id", "name", "email"],
        properties: {
            id: { type: "number" },
            name: { type: "string" },
            email: { type: "string" }
        }
    };
    pm.response.to.have.jsonSchema(schema);
});

Pre-requestスクリプトの活用

「Pre-request」スクリプトは、リクエスト送信前に実行されるスクリプトです。動的なデータの生成やトークンの取得に活用できます。

// タイムスタンプを生成して変数に設定
pm.environment.set("timestamp", new Date().toISOString());

// ランダムなメールアドレスを生成
const randomEmail = `user_${Date.now()}@example.com`;
pm.environment.set("random_email", randomEmail);

// 前のリクエストで取得したトークンを設定
// （ログインAPIのテストスクリプトでトークンを保存済みの場合）
const token = pm.environment.get("auth_token");
if (!token) {
    console.log("認証トークンが未設定です");
}

リクエストチェーンの構築

あるリクエストのレスポンスを次のリクエストで使用する「リクエストチェーン」は、実務で頻繁に使うパターンです。

// ログインAPIのテストスクリプト
pm.test("ログイン成功", function () {
    pm.response.to.have.status(200);
    const jsonData = pm.response.json();
    // トークンを環境変数に保存
    pm.environment.set("auth_token", jsonData.token);
    pm.environment.set("user_id", jsonData.user.id);
});

保存されたトークンやユーザーIDは、後続のリクエストで{{auth_token}}、{{user_id}}として参照できます。

Collection Runnerでテストを一括実行

Collection Runnerは、コレクション内のすべてのリクエストを順番に実行し、テスト結果をまとめて確認する機能です。

基本的な実行方法

コレクション名の横にある「Run」ボタンをクリックすると、Runner画面が開きます。実行するリクエストの選択、繰り返し回数、遅延時間などを設定し、「Run」で一括実行します。

実行結果はサマリー画面で確認でき、テストの成功数、失敗数、各リクエストの詳細結果が一覧表示されます。

データ駆動テスト

CSVまたはJSONファイルからテストデータを読み込み、データ駆動テストを実行できます。

// data.csv
email,password,expected_status
admin@example.com,admin123,200
user@example.com,user456,200
invalid@example.com,wrong,401
,password,400
user@example.com,,400

Runnerの「Data」セクションでCSVファイルを指定し、リクエストボディやテストスクリプトで{{email}}、{{password}}として参照します。各行のデータに対してリクエストが順番に実行され、さまざまなパターンのテストを自動化できます。

Newmanによるコマンドラインからの実行

Newmanは、Postmanのコレクションをコマンドラインから実行するためのツールです。CI/CDパイプラインに組み込んで、APIテストを自動実行できます。

# Newmanのインストール
npm install -g newman

# コレクションの実行
newman run collection.json -e environment.json

# HTML形式のレポート出力
npm install -g newman-reporter-htmlextra
newman run collection.json -e environment.json -r htmlextra

GitHub ActionsなどのCI/CDツールにNewmanを組み込むことで、コードの変更時に自動的にAPIテストが実行される仕組みを構築できます。

実務で使えるTipsとベストプラクティス

Postmanを実務で効果的に活用するためのTipsを紹介します。

APIモックサーバーの作成

フロントエンド開発でバックエンドAPIがまだ完成していない場合、Postmanのモックサーバー機能が役立ちます。コレクション内のリクエストに対してレスポンス例を設定するだけで、モックサーバーのURLが発行されます。

フロントエンドチームはモックサーバーを使って開発を進め、バックエンドの完成後に実際のAPIに切り替えるだけで済みます。

APIモニタリングの設定

Postmanのモニター機能では、コレクションのテストを定期的に自動実行できます。本番環境のAPIに対して定期的にヘルスチェックを行い、異常があればメールやSlackで通知する設定が可能です。

curlインポート機能の活用

ブラウザの開発者ツールやドキュメントでcurlコマンドが提供されている場合、Postmanに直接インポートできます。「Import」ボタンからcurlコマンドをペーストするだけで、自動的にPostmanのリクエスト形式に変換されます。

逆に、Postmanで作成したリクエストをcurlコマンドやその他の言語のコード（JavaScript、Python、PHPなど）にエクスポートすることもできます。リクエストの右側にある「Code」ボタンから利用できます。

コレクション設計のベストプラクティス

RESTの規約に沿った命名：リクエスト名に「GET ユーザー一覧」「POST ユーザー作成」のようにHTTPメソッドを含めると分かりやすくなります。

説明文の充実：各リクエストに説明、パラメーターの説明、レスポンス例を記載しておくと、APIドキュメントとしても機能します。

認証はコレクションレベルで設定：個々のリクエストではなく、コレクションの認証タブで一括設定すると、管理が楽になります。

まとめ：PostmanでAPI開発を効率化しよう

本記事では、Postmanの基本操作からテスト自動化、CI/CD連携まで幅広く解説しました。

Postman活用のステップを整理します。

まずはリクエストを保存する習慣をつける：curlやブラウザで確認していたリクエストをPostmanに保存し、コレクションとして整理しましょう。

環境変数を設定する：開発環境と本番環境のURLやトークンを環境変数で管理し、ワンクリックで切り替えられるようにしましょう。

テストスクリプトを書く：ステータスコードの検証から始め、徐々にレスポンスボディの検証、スキーマ検証へと充実させましょう。

チームで共有する：コレクションをチームで共有し、API仕様の共通理解を維持しましょう。新メンバーのオンボーディングにも効果的です。

CI/CDに組み込む：Newmanを使ってAPIテストをCI/CDパイプラインに組み込み、リグレッションを自動検出する体制を構築しましょう。

Postmanは無料プランでも十分に強力です。API開発に携わるエンジニアであれば、必ず導入しておくべきツールの一つです。