株式会社織翔
← コラム一覧に戻る
API6分で読める

PostmanでAPIのリクエスト・レスポンスを確認する基本手順

APIの疎通確認をPostmanで行うときに見るべき項目を、リクエスト作成からレスポンス確認まで実務目線でまとめます。

#API#Postman#テスト#開発効率化

PostmanはAPI確認の入口になる

API開発では、画面を作る前にリクエストとレスポンスを確認したい場面がよくあります。Postmanを使うと、ブラウザやフロントエンド実装を用意しなくても、APIに直接リクエストを送り、結果を確認できます。

特に、バックエンドとフロントエンドを分担している場合や、外部サービスと連携する場合には、期待通りの形式でデータが返っているかを早い段階で確認できます。

Postmanで見るべきなのは「返ってきたか」だけではなく、「画面や連携先がそのまま使える形で返っているか」です。

まず確認する項目

PostmanでAPIを確認するときは、URLを入力して送信するだけで終わらせず、次の項目を見ます。

  • HTTPメソッドが正しいか
  • エンドポイントのURLが正しいか
  • Query ParamsやPath Parameterが想定通りか
  • Authorizationの設定が必要か
  • Headerに必要な値が入っているか
  • Bodyの形式がAPI仕様と合っているか
  • ステータスコードが期待通りか
  • レスポンスJSONのキーと値が画面実装に使える形か

この確認を習慣にすると、画面側の不具合なのか、API側の不具合なのかを切り分けやすくなります。

リクエストを作る流れ

基本的な流れはシンプルです。

  1. Collectionを作る
  2. Requestを追加する
  3. HTTPメソッドを選ぶ
  4. URLを入力する
  5. Params、Headers、Body、Authorizationを設定する
  6. Sendを押してレスポンスを確認する

Bodyを送る場合は、API仕様に合わせて raw と JSON を選ぶことが多いです。

{
  "name": "山田 太郎",
  "email": "sample@example.com",
  "message": "問い合わせ内容のサンプルです"
}

Params、Headers、Bodyの役割

API確認で混乱しやすいのが、どこに値を入れるかです。

  • Params: 検索条件、ページ番号、絞り込み条件などURLに付く値
  • Headers: 認証情報、Content-Type、Acceptなどリクエスト全体の追加情報
  • Body: 登録・更新したいデータ本体

たとえば問い合わせ作成APIなら、名前やメールアドレスはBodyに入ることが多いです。一方、一覧取得APIのページ番号や検索キーワードはParamsに入ることが多いです。

環境変数を使って事故を減らす

API確認では、ローカル、検証、本番など接続先が変わることがあります。毎回URLを手で書き換えていると、本番に誤ってテストデータを送る危険があります。

Postmanでは環境変数を使い、次のようにベースURLやトークンを切り替えられます。

{{base_url}}/api/contact
{{access_token}}

環境ごとに base_url を変えておけば、Request自体は同じまま接続先だけを切り替えられます。チームで共有するCollectionでは、個人のトークンや本番の秘密情報を直接書かないことも重要です。

認証があるAPIの確認

認証が必要なAPIでは、Authorizationの設定を確認します。Bearer Token、Basic認証、API Key、Cookieベース認証など、方式によって設定場所が変わります。

Bearer Tokenなら、Headerに次のような値が入ります。

Authorization: Bearer xxxxxxxx

認証エラーが出た場合は、トークンが正しいかだけでなく、有効期限、権限、接続先環境、Header名の誤りも確認します。トークンが正しくても、権限が足りない場合は 403 になることがあります。

レスポンス確認で見るべきこと

レスポンスでは、まずステータスコードを確認します。成功なら 200 や 201、入力エラーなら 400 や 422、認証エラーなら 401 や 403 が返ることが多いです。

次に、レスポンス本文を確認します。画面で必要な値があるか、キー名が仕様と合っているか、エラー時のメッセージが利用者に表示できる内容かを見ます。

Postmanでは、レスポンス本文だけでなく、Headers、Cookies、レスポンスタイム、サイズなども確認できます。外部API連携では、レスポンスが成功していてもレート制限やキャッシュに関するヘッダーが重要になることがあります。

異常系も確認する

API確認では成功パターンだけでなく、異常系を先に確認しておくと手戻りが減ります。

  • 必須項目を空にしたらどう返るか
  • メールアドレス形式が不正ならどう返るか
  • 認証トークンが無い場合はどう返るか
  • 存在しないIDを指定したらどう返るか
  • 権限がないユーザーで実行したらどう返るか
  • 同じリクエストを連続送信したら二重登録されないか

画面側は、成功レスポンスよりも**エラーレスポンスの扱いで品質差が出ます。**Postmanで異常系のレスポンスを確認しておくと、画面実装時に「どのメッセージを出すか」「どの入力欄にエラーを出すか」を決めやすくなります。

テストスクリプトで確認を残す

Postmanでは、レスポンスに対する簡単なテストも書けます。毎回目視で確認するだけでなく、ステータスコードやレスポンス構造をチェックしておくと、API変更時の気づきが早くなります。

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

pm.test("has id", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("id");
});

これは本格的な自動テストの代わりではありませんが、API仕様の確認メモとして役立ちます。

Collectionをどう整理するか

APIが増えてくると、Requestが散らかります。Collectionは、機能単位やリソース単位で整理すると探しやすくなります。

  • Auth
  • Users
  • Orders
  • Contacts
  • Admin
  • External APIs

また、Request名には**「何を確認するAPIか」が分かる名前**を付けます。test1 や sample のような名前が増えると、後から誰も使えないCollectionになります。

まとめ

Postmanは、APIをただ叩くためのツールではなく、仕様と実装のズレを早く見つけるための確認場所です。

画面実装に入る前にAPIの入力・出力を整理しておくと、後工程の手戻りを減らせます。小さな確認を積み重ねることが、結果的に開発全体のスピードと品質につながります。