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

この記事で確認する一つのAPI

この記事では、読者自身が管理するAPIの {{baseUrl}}/api/users/42 をPostmanで更新する、一つのend-to-end例を通して説明します。インターネット上の架空の公開APIへリクエストを送る手順ではありません。

例では「ユーザー42の氏名とメールアドレスを部分更新し、通知を有効にする」というAPI契約を仮定します。実際に送信する前に、読者自身のAPI仕様、検証環境、更新してよいテストデータを確認してください。method、query、body、status、responseのいずれかが実APIと違う場合は、API仕様を正本としてRequestとtestを同時に直します。

Postmanで見るべきなのは「返ってきたか」だけではなく、リクエストとレスポンスが同じAPI契約を表しているかです。

事前に変数を準備する

Environmentに次の変数を作ります。

Postman v12の現行Docsでは、collection、environment、global variableの値は既定で自分のPostman instanceだけで使う local value とされ、cloudへ同期される値を shared value と呼びます。旧UIの「Current value／Initial value」は以前の用語です。詳細はPostman公式のvariablesを確認してください。

accessToken のような秘密値はlocal valueとして扱い、shared valueへ切り替えないでください。より明確に分離する場合はPostman Vaultを使います。クラウド実行やCIへ広げる場合も、tokenは実行環境のsecret管理から渡します。

Requestを一つの契約として作る

CollectionへRequestを追加し、名前を「ユーザー42を更新」のように目的が分かるものにします。以下の設定はすべて同じRequestに入れます。

1. MethodとURL

methodは PATCH、URLは次のとおりです。

{{baseUrl}}/api/users/42

この例は部分更新なので PATCH を選びます。読者自身のAPIがリソース全体の置換を PUT で定義している場合は、その仕様に従い、必要な全項目をbodyへ含めます。

2. Authorization

AuthorizationタブでTypeを Bearer Token にし、Tokenへ次を設定します。

{{accessToken}}

Postmanは送信時に次のHTTP headerを組み立てます。tokenの実値をRequest本文、説明、script、exampleへ貼り付けないでください。

Authorization: Bearer {{accessToken}}

3. Query Params

Paramsタブへ次を追加します。

送信されるURLは次の形です。

{{baseUrl}}/api/users/42?notify=true

notify はHTTP共通仕様ではなく、この例で仮定したAPI固有のqueryです。実APIに存在しなければ追加せず、そのAPI仕様にあるqueryだけを使います。

4. Request Headers

Headersは次を設定します。BodyタブでJSONを選ぶと Content-Type が自動設定される場合もありますが、送信直前に実値を確認します。

Accept: application/json
Content-Type: application/json

5. JSON Body

Bodyタブで raw、形式で JSON を選び、次を入力します。

{
  "firstName": "Test",
  "email": "user42@example.test"
}

.test は例示用に予約されたドメインで、Test もテストfixtureの値です。このbodyは実在人物の情報や本番データではありません。APIがsnake_caseを契約にしている場合は first_name へ置き換え、response testも同じ表記へ揃えます。

期待するResponseを先に定義する

この更新APIの例では、成功時のstatusを 200 OK とし、更新後の表現をJSONで返す契約を仮定します。

期待するresponse headers:

Content-Type: application/json

期待するJSON body:

{
  "data": {
    "id": 42,
    "firstName": "Test",
    "email": "user42@example.test"
  }
}

これはPostmanで観測した実行結果ではなく、Requestとtestを一貫させるための期待値テンプレートです。API仕様が更新成功を 204 No Content と定義するなら、JSON bodyを期待してはいけません。RFC 9110の204は、204 responseがheader sectionの終端で完了し、contentを含められないと定めています。

Post-response testを追加する

ScriptsのPost-responseタブへ、次のtestを追加します。Postman公式Docsでも、response受信後の検証はpost-response scriptへ記述します。

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

pm.test("content type is JSON", () => {
  pm.expect(pm.response.headers.get("Content-Type")).to.include(
    "application/json",
  );
});

pm.test("updated user matches the contract", () => {
  const json = pm.response.json();

  pm.expect(json.data.id).to.eql(42);
  pm.expect(json.data.firstName).to.eql("Test");
  pm.expect(json.data.email).to.eql("user42@example.test");
});

このtestは、method、URL、body、期待status、response header、JSON bodyを同じ更新契約へ揃えています。headerの検証方法はPostman公式のtest script examplesでも確認できます。

実行前にEnvironmentが検証用であることと、ユーザーID 42 が更新してよいデータであることを再確認します。Send後はtestの合否だけでなく、実際のRequest URL、送信header、response bodyもAPI仕様と照合します。

エラー時はステータスと本文を一緒に読む

ステータスだけで原因を決めつけず、API仕様とエラー本文を照合します。代表的な意味はRFC 9110で確認できます。

Laravel側の契約と揃える

Laravel APIでcamelCaseの firstName を返すなら、JsonResource にそのキーを明示し、Feature testでも同じJSON pathを固定します。実装例はLaravelのスネークケースとキャメルケースを参照してください。

Postmanだけで期待値を管理すると、バックエンドの変更とずれることがあります。OpenAPIなどのAPI仕様、LaravelのFeature test、PostmanのRequest／post-response testを同じ変更で更新します。

Collectionとして繰り返し実行する

Requestとtestが安定したらCollectionへ保存し、PostmanのCollection Runnerでまとめて実行できます。RunnerではEnvironment、実行順、iteration data、test結果を確認します。更新系Requestを繰り返す場合は、テストデータの初期化と冪等性をAPI仕様に合わせて設計してください。

CIへ広げる場合は、GitHub ActionsでLaravelテストを自動化する基本を参照し、外部疎通のジョブは検証用のデータと権限で実行します。