初めて「APIを叩く」｜Postmanで学ぶAPIの基本

はじめに

こんにちは。ソーイ株式会社の工藤です。

本記事では、API実装時の動作確認やテストでよく利用しているPostmanについて、APIの基本からPostmanで実務的によく使う機能までを整理しました。

結論

Postmanを使うと、Method・Headers・Body・認証情報を画面上で自由に組み立ててAPIにリクエストを送り、その場でレスポンスを確認できます。Collection・Environment・Authorizationといった機能を組み合わせることで、開発時の動作確認から検証環境でのテストまで、同じ手順でAPIを試せるようになります。

想定読者

• これからAPI開発やAPIのテストに関わる初心者エンジニア

この記事でわかること

• APIとPostmanの関係
• Postmanで実務的によく使う基本機能5つ
• トークン認証（Bearer Token）の設定方法

APIとは

まずは前提となるAPIについて軽くおさらいします。

API（Application Programming Interface）とは、アプリケーション同士がデータをやり取りするための窓口です。

例えば天気予報アプリを考えてみると、アプリ自身が気象データを観測しているわけではなく、気象情報を提供している外部のサービスにリクエストを送り、その結果（レスポンス）を受け取って画面に表示しています。このときの「リクエストを送ってレスポンスを受け取る」やり取りのルールを定めたものがAPIです。

Web API（HTTPを使ったAPI）では、主に以下のような要素でやり取りを行います。

• Method：GET（取得）、POST（作成）、PUT（更新）、DELETE（削除）など、何をするリクエストかを示す
• URL（エンドポイント）：どこに対してリクエストを送るか
• Headers：認証情報やデータ形式などの付加情報
• Body：送信するデータの中身（POST・PUTなどで使用）

APIとPostman

APIの中身がわかったところで、「これをどうやって試すのか」という話になります。

GETリクエストだけであれば、ブラウザのアドレスバーにURLを入力するだけでも確認できます。しかし、POSTでデータを送ったり、Headersに認証トークンを付けたりといった操作は、ブラウザだけでは簡単にはできません。

ちなみに、エンジニア同士の会話では「APIを叩く」という言葉がよく使われます。これは「APIに対してリクエストを送り、レスポンスを受け取る」という一連の動作を指すエンジニア用語です。「このエンドポイント、一回叩いて結果見てみて」のように使われ、まさにPostmanはこの「APIを叩く」作業をGUI上で手軽に行うためのツールだと言えます。

そこで登場するのがPostmanです。Postmanを使うと、Method・Headers・Bodyを画面上で自由に組み立てて送信し、その場でレスポンスを確認できます。コードを書かずにGUI上でAPIを試せるため、バックエンド開発者がAPIを実装したときの動作確認はもちろん、フロントエンド開発者がバックエンドのAPI仕様を把握しながら開発を進める際にも重宝するツールです。

具体的にどんなことができるのか、次の章で基本機能を5つ厳選して紹介します。

Postmanの始め方

Postmanは公式サイトからアカウントを登録すれば、すぐに使い始められます。デスクトップアプリ版と、ブラウザ上で動くWeb版が用意されており、まずはインストール不要なWeb版で試してみるのがおすすめです。

1. Postman公式サイトにアクセスし、無料アカウントを作成する
2. ログイン後、画面左上の「New」からリクエストを作成する画面に進む

ここまでできれば、次の章で紹介する基本機能をすぐに試せます。

Postmanでできることの基本

Postmanには非常に多くの機能がありますが、まずは実務でよく使う5つに絞って紹介します。

1. リクエストの作成・送信

Postmanの基本動作です。画面上部でMethodを選び、URLを入力し、必要に応じてHeadersやBodyを設定して「Send」を押すだけでリクエストを送信できます。

本記事のサンプルには、誰でも自由に使える無料のテスト用API「JSONPlaceholder」を使用しています。手元にAPIを用意しなくても、そのままコピーして試すことができます。

Method: POST
URL: https://jsonplaceholder.typicode.com/users
Headers:
  Content-Type: application/json

Body（raw / JSON）には以下を入力します。

Body (raw / JSON):
  {
    "name": "Taro Yamada",
    "email": "[e-mail]"
  }

Sendを押すと、ステータスコード 201 Created とともに、IDが付与されたデータがレスポンスとして返ってきます。

curlコマンドで同じことをやろうとすると以下のようになりますが、Postmanならフォームに入力するだけで同じリクエストを組み立てられます。

curl -X POST https://jsonplaceholder.typicode.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Taro Yamada","email":"[e-mail]"}'

Postmanからcurlコマンドを生成できます

逆に「Postmanで組み立てたリクエストをcurlコマンドで確認したい」という場面でも、Postmanが役立ちます。リクエスト画面右側の「Code」アイコン（>）をクリックすると、言語・ライブラリ別のコードスニペットが表示され、cURLを選ぶと対応するcurlコマンドがそのまま得られます。チームメンバーへ手順を共有するときや、CI/CDでの自動化の参考にする際に便利です。

2. Authorization（認証）の設定

実際にAPIを実装していると、動作確認の際にトークン認証が必須になるケースは少なくありません。筆者が今回実装したAPIも例に漏れず、リクエストごとにアクセストークンをAuthorizationヘッダーへ付与する必要がありました。

Headersタブに直接 Authorization: Bearer xxxxx を追加することもできますが、Postmanには専用の「Authorization」タブが用意されており、こちらを使う方が手軽です。

1. Authorizationタブを開く
2. Typeで「Bearer Token」を選択
3. Tokenの欄に取得したアクセストークンを貼り付ける

これだけで、リクエスト送信時に自動的に以下のヘッダーが付与されます。

Authorization: Bearer eyJh...

毎回トークンを手入力するのは手間なので、後述のEnvironment / Variablesと組み合わせて、Tokenの欄に {{access_token}} のように変数を指定しておくと便利です。トークンの有効期限が切れて更新が必要になった場合も、Environment側の値を書き換えるだけで、紐づく全リクエストに反映されます。

3. Collectionでリクエストをまとめて管理

作成したリクエストは「Collection」という単位でフォルダのように整理できます。

例えば「ユーザー管理API」というCollectionの中に、「ユーザー作成」「ユーザー一覧取得」「ユーザー削除」といったリクエストをまとめておけば、必要なときにすぐ呼び出せます。チーム開発であればCollectionを共有することで、メンバー間でAPIの叩き方を揃えることもできます。

4. Environmentで環境を切り替える

開発環境・検証環境・本番環境など、APIのURLや認証情報は環境ごとに異なることがほとんどです。そのたびにURLを書き換えるのは手間がかかります。

Postmanの「Environment」機能を使うと、環境ごとに変数を定義しておき、リクエスト側では変数名だけを記述できます。

URL: {{base_url}}/users

base_url という変数に、開発環境用のドメインと本番環境用のドメインをそれぞれ登録しておけば、画面右上のEnvironmentを切り替えるだけで、同じリクエストを別の環境に対して送信できます。APIキーなどの認証情報も同様に変数化しておくと、リクエストの中に直接書く必要がなくなり安全です。

5. レスポンスの確認

リクエストを送信すると、画面下部にレスポンスが表示されます。ステータスコード（200, 404, 500など）、レスポンスタイム、レスポンスボディ（JSONなど）を一目で確認できるため、「APIが期待通りに動いているか」をすぐに判断できます。

JSON形式のレスポンスは自動的に整形されて表示されるので、生のレスポンスを目で追うよりもずっと見やすいのもポイントです。

まとめ

今回はAPIの基本から、Postmanで実務としてよく使う基本機能を整理しました。

• APIはアプリケーション同士がデータをやり取りするための窓口
• Postmanを使うと、Method・Headers・Body・認証情報を自由に組み立ててAPIを手軽に試せる
• 「リクエストの送信」「Authorization（Bearer Token）での認証」「Collectionでの管理」「Environment / Variablesでの環境切り替え」「レスポンス確認」の5つが基本機能

お知らせ

技術ブログを週1〜2本更新中、ソーイをフォローして最新記事をチェック！
https://qiita.com/organizations/sewii