Postman入門｜API開発中の動作検証を直感的に行う方法を解説

こんにちは！SiiD代表エンジニアのセイトです。

Postmanというツールをご存知でしょうか？
PostmanはWeb APIの開発やテストを効率化するためのアプリケーションで、Webやデスクトップアプリで展開されている開発ツールです。

https://www.postman.com/

実際のシステム開発ではシステム間でAPIを用いたデータ連携の機会があるかと思います。
これの動作確認や検証をしたい際に、Postmanを使うとコードを書かず、HTTPリクエストの送信を画面上のGUIで簡単に行えるのが大きな特徴です。

パラメータや認証情報を設定して送信ボタンを押すだけで即座にレスポンスを確認できるため、自分が作ったAPIの動作確認はもちろん、外部APIの仕様を素早く理解する際にも重宝します。

この記事では、そんなPostmanを使ってAPIの動作検証を行う方法を解説します。

APIとは

Postmanの紹介の前に、そもそもAPIって何？と思う方のために軽くAPIについても解説します。

APIは Application Programming Interface の略で、ソフトウェア同士が決められた形式でやり取りするための窓口です。
中でもWeb上でHTTP通信を通じてやり取りするものをWeb APIと呼び、この記事で扱うのもこのWeb APIです。

たとえば天気予報アプリが気象データを表示できるのは、裏側で気象サービスのAPIにリクエストを送り、返ってきたデータを画面に反映しているからです。自分でシステムを作る場合も、フロントエンドとバックエンドの間や、自社システムと外部サービスの間で、このAPIを介したデータ連携が発生します。

Web APIの基本はシンプルで、こちらからリクエスト（要求）を送ると、相手のサーバーがレスポンス（応答）を返す、という往復です。Postmanはこのリクエストの組み立てと送信、レスポンスの確認を、コードを書かずに画面上で行うためのツールになります。

REST APIとは

現在のWeb APIで最も広く使われている設計スタイルが REST（REpresentational State Transfer）です。
「どんなルールでAPIを設計するか」という型の１つで、もっとも主流なものです。他にGraphQLなどがあります。
RESTでは、扱うデータ（リソース）を1つのURLで表します。このデータの所在を示すURLをエンドポイントと呼びます。

たとえばPokeAPIでは、ピカチュウのデータは次のエンドポイントで表されます。

https://pokeapi.co/api/v2/pokemon/pikachu

そして「そのリソースに対して何をするか」を、次に説明するHTTPメソッドで指定します。レスポンスのデータ形式には、キーと値の組み合わせでデータを表現するJSONが使われるのが一般的です。この記事で扱うPokeAPIもJSONPlaceholderも、RESTに沿ったAPIです。

HTTPメソッドについて

HTTPメソッドは、エンドポイントが指すリソースに対してどんな操作を行うかを表す指定です。主に使われるのは次の4つです。

メソッド	操作	用途の例
GET	取得	データを読み取る（一覧・詳細の取得）
POST	作成	新しいデータを送って登録する
PUT	更新	既存のデータを書き換える
DELETE	削除	データを削除する

つまりリクエストは「どのエンドポイントに」「どのメソッドで」送るかで大枠が決まります。この記事では、データを取得するGETと、データを送るPOSTの2つを実際に動かします。

Postmanのセットアップ

Postmanにはデスクトップアプリ版とブラウザで動くWeb版があります。この記事では、インストール不要ですぐ試せるWeb版を使います。

Postman公式サイトにアクセスします。
「Sign Up for Free」または「Try the New Postman」ボタンから無料アカウントを作成します。メールアドレスのほか、Googleアカウントでも登録できます。
サインイン後、ブラウザ上に操作画面が表示されます。

初回はワークスペースの選択を求められることがあります。ワークスペースはリクエストやコレクションを保存する作業単位で、最初から用意されている「My Workspace」を使えば問題ありません。
見つからないときは、左上のホームアイコンをクリック→「Workspaces」から確認できます。

リクエストを作成するには、画面上部のタブ列にある「＋」をクリックして新しいリクエストタブを開きます。

タブを開くと、リクエストを組み立てる基本要素が並びます。

左のドロップダウン：HTTPメソッド（GET / POST など）を選ぶ場所です。初期値はGETです。
中央の入力欄：リクエストの送信先URL（エンドポイント）を入力します。
右の「Send」ボタン：リクエストを送信します。
画面下部：送信後にレスポンスが表示される領域です。

（なお、Web版は「Cloud Agent」という仕組み経由でリクエストを送信します。
今回のような公開APIであれば初期設定のままで問題なく、送信時に接続エラーが出た場合のみ、画面下部の接続先がCloud Agentになっているかを確認してください。）

[GET編] PostmanでPokeAPIを操作してみる

まずはデータを取得するGETから試します。題材のPokeAPIは、ポケモンのデータをJSONで返してくれる公開APIで、アカウント登録もAPIキーも不要です。

リクエストの説明

メソッドのドロップダウンがGETになっていることを確認し、URL欄に次のエンドポイントを入力します。

https://pokeapi.co/api/v2/pokemon/pikachu

URL末尾の pikachu が、取得するリソースの指定です。
ここを charizard や ditto など別のポケモン名に変えれば、そのポケモンのデータが返ります。入力できたら「Send」を押します。

これで「PokeAPIのこのエンドポイントに、GETでリクエストを送る」という指定が完成します。GETはデータを取得するだけなので、設定するのはメソッドとエンドポイントの2つだけです。

レスポンスの説明

送信すると、画面下部のレスポンス領域にJSONが表示されます。右上の「200 OK」はステータスコードで、リクエストが成功したことを示します。その隣には応答時間（Time）とデータサイズ（Size）も表示されます。

本文はJSON形式で、"キー": 値 の組み合わせが並んでいます。冒頭には "abilities"（とくせい）が並び、static や lightning-rod といったピカチュウの特性が確認できます。少し読み進めると、次のような値も含まれています。

"id": 25,
"name": "pikachu",
"height": 4,
"weight": 60

JSONでは、{ } で囲まれた1件のまとまりをオブジェクト、[ ] で囲まれた並びを配列と呼びます。先ほどの "abilities": [ ... ] は、特性が複数入った配列です。レスポンスのJSONは、このオブジェクトと配列の入れ子として読み解けます。

PokeAPIのレスポンスは項目が多く数千行になりますが、全体を読む必要はありません。目的の項目だけ確認したいときは、レスポンス領域で ⌘+F（WindowsはCtrl+F）を押し、キーワードで検索するとその箇所にジャンプできます。

なお、存在しないポケモン名を指定するとステータスコードは 404 Not Found になり、リソースが見つからなかったことを示します。ステータスコードはレスポンスの成否を判断する最初の手がかりになるので、200（成功）・404（対象なし）・500番台（サーバー側のエラー）だけでも覚えておくと役立ちます。

[POST編] PostmanでJSONPlaceholderを操作してみる

次はデータを送るPOSTです。PokeAPIはGET専用でPOSTを受け付けないため、ここではPOSTを試せる公開API「JSONPlaceholder」を使います。送られたデータを受け取り、作成結果を返す動きを安全に確認できるテスト用のAPIです。

リクエストの説明

GETと違い、POSTでは送信するデータ（リクエストボディ）を自分で用意します。手順は次のとおりです。

メソッドのドロップダウンをGETから POST に変更します。
URL欄にエンドポイント https://jsonplaceholder.typicode.com/posts を入力します。
URL欄の下の「Body」タブを開きます。ここが送信データを記述する場所です。
「raw」を選び、右端の形式を「Text」から「JSON」に変更します。
入力エリアに、送信するデータをJSONで記述します。

今回は、投稿を1件作成するデータとして次のJSONを送ります。

{
  "title": "はじめての投稿",
  "body": "PostmanからPOSTを送っています",
  "userId": 1
}

記述できたら「Send」を押します。Content-TypeなどのヘッダーはPostmanがJSON形式に合わせて自動で付与するため、この例では手動設定は不要です。

レスポンスの説明

レスポンスとして、次のようなJSONが返ります。

{
  "title": "はじめての投稿",
  "body": "PostmanからPOSTを送っています",
  "userId": 1,
  "id": 101

確認したい点は2つです。1つはステータスコードが 201 Created になっていること。
これはリソースが新しく作成されたことを示すコードです。もう1つは、送信したデータに "id": 101 という識別子が付与されて返っている点です。作成したデータにサーバーが管理用のIDを割り当てて返すのは、REST APIでよく見られる挙動です。

ただしJSONPlaceholderはテスト用のため、POSTを送っても実際にはデータは保存されません。
あくまで「作成された場合の応答」を返すだけで、同じIDで取得し直しても存在しない点には注意してください。POSTのリクエストとレスポンスの流れを確認する用途には十分です。

【補足】Curlコマンドとの棲み分け

APIにリクエストを送る手段はPostmanだけではありません。実務でよく併用されるのが、ターミナルからHTTPリクエストを送るコマンド curl です。同じことができるなら、どちらを使えばよいのか整理しておきます。

Postmanが向いているのは、リクエストを画面上で組み立てながら仕様を探ったり、作ったリクエストをコレクションとして保存・共有したりする場面です。パラメータや認証を試行錯誤しながらAPIの動作を確認する用途に強く、チームでの共有やドキュメント化にも向いています。

一方のcurlは、コマンド1行で完結するため、シェルスクリプトやCIへの組み込み、SSH接続先のサーバー上での確認、手順を1行で共有したいときに便利です。GUIを立ち上げずにサッと叩けるのも利点です。両者は排他ではなく、探索や設計はPostman、自動化や再現はcurl、というように使い分ける／併用するのが実際のところです。

そしてPostmanには、組み立てたリクエストをcurlコマンドへ変換する機能があります。

画面右上付近にあるアイコンをクリックすると右側にサイドバーが開きます。
サイドバー上部のコードアイコンをクリックするとコードのタブ画面が開きます。
四角いアイコンをクリックするとクリップボードにコピーされます。

リクエストを開いた状態で画面右の「Code」から言語一覧を開き「cURL」を選ぶと、同じ内容のcurlコマンドが生成されます。
他の言語コマンドにすることも可能です。

たとえば、GET編で送ったリクエストは次のコマンドに相当します。

curl https://pokeapi.co/api/v2/pokemon/pikachu

POST編のリクエストであれば、次のようになります。

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"はじめての投稿","body":"PostmanからPOSTを送っています","userId":1}'

-X でメソッド、-H でヘッダー、-d で送信データを指定します。POST編でPostmanが自動付与していたContent-Typeヘッダーも、curlに書き出すとこの -H の行として明示されます。
画面で設定した項目が、そのままコマンドのオプションに対応しています。まずはPostmanで組み立て、必要に応じてcurlへ書き出す、という流れが実務では扱いやすいでしょう。