Postmanの使い方｜APIテストの基本操作と実践例

Postmanを使うと、APIにリクエストを送り、返ってきたレスポンスをその場で確認し、簡単な自動テストまでまとめて実行できます。フロントエンド開発でバックエンドの動作を確かめたいとき、社内APIの疎通確認をしたいとき、API仕様書どおりに返るかをチェックしたいときに便利です。

特に入門段階では、「URLを叩く」「ヘッダーを付ける」「JSONを送る」「想定どおりの値か検証する」の4つを最初に押さえると、実務で使える形になりやすくなります。この記事では、Postman Echo を使って安全に試せる最小構成の例で、基本操作からテストまで順に整理します。

• できること: GET/POST送信、ヘッダー設定、JSON送信、レスポンス確認、簡単な自動テスト
• 向いている場面: APIの疎通確認、開発中の検証、仕様確認、手動テストの標準化
• 対象環境: 2026年4月時点のPostman公式ドキュメントに基づく。Postman desktop app を中心に説明
• すぐ試す方法: https://postman-echo.com/get にGETリクエストを送る

ここがポイント: Postmanは「APIを送って結果を見るツール」で終わりません。コレクション、変数、テストを組み合わせると、毎回同じ確認を再現できる形に変えられます。

Postmanで最初に覚える3つの画面

最初に全部の機能を追う必要はありません。まずは次の3つで十分です。

リクエスト作成画面

ここでHTTPメソッド、URL、ヘッダー、Bodyを設定します。

• GET: データ取得
• POST: データ作成や送信
• PUT / PATCH: 更新
• DELETE: 削除

レスポンス表示エリア

Send を押すと、画面下部にレスポンスが表示されます。ここで見るべき項目は次の4つです。

• ステータスコード: 200、201、400、401、404 など
• Body: JSONや文字列の中身
• Headers: サーバーが返したヘッダー
• Time: 応答時間

実務では、単にBodyを見るだけでなく、「成功したか」「遅すぎないか」「期待したキーがあるか」まで確認します。

Collections

Collectionsは、リクエストを保存してまとめる機能です。単発確認だけならタブで足りますが、実務では同じAPIを何度も叩きます。

• 開発用API
• 検証用API
• 本番前確認用API

このように目的別にまとめておくと、確認漏れが減ります。

前提環境と最初の設定

Postman公式ドキュメントでは、Desktop Appの利用が推奨されています。Web版でも使えますが、エージェントの種類によってはCORS制約や機能差が出ます。

最初の選び方はシンプルです。

• 迷ったら Postman desktop app
• Web版を使うなら Desktop Agent を優先
• ブラウザだけで送る場合はCORS制約に注意

また、認証情報を扱う予定があるなら、最初から変数を使う癖をつけたほうが安全です。Bearer TokenやAPI KeyをURLや本文に直書きすると、後から管理しづらくなります。

基本操作1: GETリクエストを送ってレスポンスを見る

まずは一番小さい例です。Postman Echoは、送った内容をそのまま確認しやすい学習用APIです。

手順

1. 新規リクエストを作成する
2. メソッドを GET にする
3. URLに次を入力する

https://postman-echo.com/get?userId=123&status=active

4. Send を押す

何を確認すればよいか

成功すると、レスポンスのBodyにクエリパラメータが含まれます。たとえばBodyの一部は次のように確認できます。

{
  "args": {
    "userId": "123",
    "status": "active"
  }
}

ここで見たいのは、URLに付けた値がそのまま args に入っていることです。つまり、「自分が何を送ったか」と「APIが何を受け取ったか」を対応づけて確認する練習になります。

よくあるつまずき

• URL末尾の ? や & の付け方を間違える
• 数字のつもりでも、HTTPでは文字列として返ることがある
• パラメータを Params タブで設定したのに、URLに反映されているか見ていない

特に初心者は、Bodyばかり見て「送れた」と判断しがちです。まずはURL、Params、レスポンスBodyの3点を見比べると崩れにくくなります。

基本操作2: POSTでJSONを送る

次はJSONを送る例です。業務APIではこちらのほうが頻度は高めです。

手順

• メソッド: POST
• URL: https://postman-echo.com/post
• Body タブで raw を選択
• 形式を JSON にする
• 次のJSONを入力する

{
  "name": "Sato",
  "role": "tester",
  "active": true
}

JSON を選ぶ理由は、Content-Type: application/json を正しく付けやすいからです。ここがずれると、API側がJSONとして解釈できず、400 Bad Request になることがあります。

送信時の見どころ

• ステータスコードが成功になっているか
• Headers に Content-Type が入っているか
• レスポンス内に送信内容が含まれているか

POSTの確認で大事なのは、「送信ボタンを押せたか」ではなく「サーバーが期待した形式で受け取ったか」です。JSONの中身が正しくても、ヘッダーが違えば失敗します。

実践例: 環境変数を使ってAPIテストを再利用する

実務では、開発環境と本番環境でURLだけが違うことがよくあります。そのたびにURLを手で書き換えると、確認ミスが増えます。ここで使うのが環境変数です。

例: base_url を環境ごとに切り替える

Environmentに次の変数を作成します。

• base_url = https://postman-echo.com

そのうえで、リクエストURLをこう書きます。

{{base_url}}/get?userId=123

この形にしておくと、接続先の切り替えが速くなります。学習用では小さな差ですが、実務では dev、stg、prod の切り替えで効きます。

変数を使う理由

• URLの打ち間違いを減らせる
• チームで同じリクエストを共有しやすい
• API KeyやBearer Tokenを本文に直書きしなくて済む

Postman公式でも、変数は再利用と管理のための基本機能として案内されています。特に認証情報は、変数に入れたうえで機密値として扱う前提で考えるのが安全です。

実践例: Post-responseでテストを書く

Postmanが便利なのは、送信後にJavaScriptでテストを書ける点です。毎回目視で確認していた内容を、失敗時にすぐ分かる形へ変えられます。

最小のテスト例

Scripts の Post-response に、次のコードを入れます。

pm.test("status code is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("userId is returned", function () {
  const responseJson = pm.response.json();
  pm.expect(responseJson.args.userId).to.eql("123");
});

このテストで確認していること

• APIが正常応答したか
• 期待したクエリ値が返ってきたか

この2つだけでも、手動確認の精度はかなり上がります。人が画面を見て「たぶんOK」と判断するより、条件を固定しておいたほうが再現性が高いからです。

テスト結果の見方

送信後、Test Results で成功・失敗を確認できます。失敗した場合は、どの条件が崩れたかがその場で分かります。

認証付きAPIを試すときの基本

実務APIでは、認証なしで触れるものは多くありません。最低限、次の2つは押さえておくと対応しやすくなります。

API Key

Authorization タブで API Key を選び、キー名と値を設定します。APIによってはヘッダーに入れる場合と、クエリに付ける場合があります。

Bearer Token

Authorization タブで Bearer Token を選び、トークンを設定します。JWTを使うAPIでも、この形式で試す場面は多いです。

認証情報の扱いで注意したい点

• API Keyを記事やチャットに貼らない
• Collectionに直書きせず、変数で管理する
• チーム共有前に値が残っていないか確認する

「とりあえず通ればいい」で直書きした情報が、そのまま共有される事故は珍しくありません。テスト用でも扱いは慎重にしたほうが安全です。

よくある失敗と対処法

Postmanでつまずきやすい点は、だいたい決まっています。

1. 401 Unauthorized になる

原因として多いものは次のとおりです。

• API Keyの名前が違う
• Bearer Tokenの値が古い
• 開発環境と本番環境で認証方式が違う

まず Authorization タブと Headers を見て、API仕様と一致しているか確認します。

2. 400 Bad Request になる

• JSONの構文ミス
• 必須項目の不足
• Content-Type の不一致

POSTやPUTで起きやすい失敗です。Bodyの内容だけでなく、Headers も合わせて確認します。

3. Web版で送れない

Postman公式では、Web版ではエージェントの種類によって制約があります。ブラウザ起因のCORS制限を避けたいなら、Desktop AppかDesktop Agentを前提にしたほうが安定します。

4. 変数が空になる

• Environmentを切り替えていない
• 変数名のスペルが違う
• {{base_url}} のような記法を崩している

リクエスト自体より、環境設定のミスで止まるケースは意外と多いです。

実務での使いどころ

Postmanは学習用ツールではなく、日常の確認作業を揃えるための道具として強いです。

使いどころを絞るなら、まずはこの3つです。

• バックエンド実装直後の疎通確認
• フロントエンド実装前のAPI仕様確認
• リリース前の回帰確認

特にCollectionsに保存し、変数を使い、簡単なテストを付けるところまで進めると、個人の確認作業がチームの資産になります。

curlや他ツールとの使い分け

Postmanだけが正解ではありません。用途で分けると整理しやすいです。

• curl: 端末ですぐ叩きたい、CIやシェルに組み込みたい
• Postman: 画面で確認したい、チーム共有したい、テストを残したい
• 軽量クライアント: よりシンプルなUIで管理したい

最初の1本はPostmanのほうが入りやすいですが、運用自動化まで進むなら curl やCLI系も候補になります。逆に、レスポンスを見ながら仕様確認を進める段階では、Postmanの視認性がかなり効きます。

まず再現したい最小手順

最後に、最初の10分で試す内容を絞るなら次の順番です。

• https://postman-echo.com/get にGETを送る
• クエリパラメータを付けて args を確認する
• POST でJSONを送る
• base_url を環境変数にする
• pm.test() でステータスコードを検証する

ここまでできれば、単なる「APIを叩くツール」ではなく、確認作業を再利用できるAPIテスト環境として使い始められます。次に見るべきポイントは、Collectionsをどう分けるか、認証情報をどう安全に管理するか、その2点です。

参照リンク

• Postman Docs: Send your first API request
• Postman Docs: About the Postman Agent
• Postman Docs: Test requests in Postman using the Echo API
• Postman Docs: Send a request with the Postman API client
• Postman Docs: Store and reuse values using variables
• Postman Docs: Group sets of variables in Postman using environments
• Postman Docs: Organize and automate API requests in Postman Collections
• Postman Docs: Authorization types supported by Postman
• Postman Docs: Write scripts to test API response data in Postman
• Postman Docs: Writing tests and assertions in scripts
• Postman Docs: Reference Postman responses in scripts