APIの動作を確認する方法: curlコマンドとPostman

この記事では、APIの動作を確認する方法として①curlコマンドを実行する方法と、②Postmanというツールを使う方法を解説します。

APIを用いた開発・学習をするとき、APIの動作を確認することがあります。初めてAPIを触れるときなどは、やり方がわからないと思います。

私も初めは「ドキュメントに出てくるcurlって何？」と思っていました。この記事を読むことで、APIの動作を確認する方法を学ぶことができます。

具体的には:

1. curlコマンドという開発に必要な基本知識が身につく
2. Postmanという「使いこなせると開発効率が上がるツール」について学べる

私はWebエンジニアとしてAPIを用いた開発に携わってきました。最近もcurlコマンドやPostmanを使う機会があり、自分へのメモも兼ねてこの記事を書いています。

目次

• APIの仕組み

  • HTTPメッセージ

• APIの動作を確認する方法

• ① curlコマンド

  • curlコマンドのインストール
  • 動作環境
  • curlコマンドの使い方
  • curlコマンドの例

• ② Postman

  • Postmanのインストール
  • 動作環境
  • Postmanの使用例

• おわりに

APIの仕組み

まず初めに「APIとはそもそもどんな仕組みなのか」を整理します。APIはApplication Programming Interfaceの略で、他のアプリとのやりとりを行うための窓口のことをいいます。

APIにリクエストを送ることで、アプリケーションを操作したり、何かしらのデータを受け取ることができます。

世の中にはいろんなAPIが公開されています。例えばGitHubやTwitterも、APIを通して操作したり情報を取得したりできます。

HTTPメッセージ

このAPIへのリクエストは、“HTTPメッセージ”というものでやりとりされます。APIへのリクエストであるリクエストメッセージと、APIからの応答であるレスポンスメッセージからなります。

概要図を次に示します。APIを使いたいクライアントと、APIを提供するWebサーバーとの間で、図のようなHTTPメッセージがやりとりされます:

HTTPメッセージの概要

図の左側のように、クライアントからAPIサーバーに対してリクエストメッセージを送ると、サーバー上で何らかの処理がされます。結果として、図の右側のようにサーバーからクライアントにレスポンスが返ってきます。

APIの動作を確認する方法

この記事の目的は「APIの動作を確認する方法」を学ぶことです。言いかえると、上図において「どのようなリクエストメッセージを、どうやって送るか」です。

この方法がcurlコマンドやPostmanというツールになります。

例えばcurlコマンドはどんなリクエストを送るかを指定でき、あわせてヘッダー情報を設定できます。またレスポンスとしてどんなステータスが返ってきたか、どんなヘッダー情報が設定されているかなどを表示できます。

コマンドラインから動作を確認する方法がcurlコマンドで、GUIから操作する方法がPostmanです。他にもやり方はありますが、この2つが代表的な方法になります。この2つについて解説していきます。

① curlコマンド

curlはHTTPなどさまざまなプロトコルを用いてデータを転送するライブラリ・コマンドラインツールを提供するプロジェクトです。「カール」と発音します。

curlプロジェクトが提供しているのは次の2つです:

1. ライブラリのlibcurl
2. コマンドラインツールのcurlコマンド

この記事で解説するのは2のcurlコマンドになります。curlコマンドは内部でlibcurlを用いています。プロトコルはHTTP以外にもHTTPやFTP、IMAP、POP3、SMTPなどに対応していて、いろんなツールでlibcurlが採用されています。

curlコマンドのインストール

macOSや最近のLinuxディストリビューションには標準でcurlコマンドが入っています。Windowsも、10のVer.1808からcurl.exeというコマンドが標準で付属されているようです。

curlコマンドが入っていない場合、あるいは別のバージョンを使いたい場合は公式サイトにある手順でインストールすればいいです。

動作環境

この記事の内容は、次の各バージョンで動作を確認しています:

curlコマンドの使い方

curlコマンドの基本形は次の通りです:

$ curl [options...] <url>

オプションがない場合、例えば次のコマンドの場合はURLに対してGETリクエストを送ります。この場合、結果として内容、つまりHTMLファイルが表示されます:

$ curl https://example.com

curlコマンドでよく使うオプションを表でまとめます:

curlコマンドの例

次に、よく使うcurlコマンドを例として示します。なお、ここではAPIサーバーとしてJSONPlaceholderを使っています。

JSONPlaceholderはJSON形式のテストデータを返すAPIを無料で提供しています。GETだけでなくPOSTやPUT、DELETEなどのメソッドに対応していて、curlコマンドなどの動作確認に便利なサービスです。

ステータスコードを取得する

$ curl -sS https://jsonplaceholder.typicode.com/posts/1 \
       -w "http_code: %{http_code}" \
       -o /dev/null
http_code: 200

ヘッダーとデータを指定してPOSTリクエストする

$ curl -X POST https://jsonplaceholder.typicode.com/posts \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer xxx" \
       -d '{ "userId": 1, "title": "foo", "body": "bar" }'
{
  "userId": 1,
  "title": "foo",
  "body": "bar",
  "id": 101
}

② Postman

curlコマンドはコマンドラインツールで、ターミナル.appなどのアプリケーションからコマンドとして実行します。ただ、GUIから気軽に操作したいときもあると思います。APIの動作確認ができる代表的なGUIツールがPostmanです。

Postmanは無料で利用でき、リクエストを保存して後から実行することができます。実行履歴も表示してくれたりと、APIの動作確認にとても役立つツールです。

Postmanのインストール

Postmanは公式サイトからダウンロードできます。公式サイトにしたがえばインストールできます。

動作環境

この記事の内容は、次の各バージョンで動作を確認しています:

Postmanの使用例

例として、前述したcurlコマンドの「ヘッダーとデータを指定してPOSTリクエストする」例をやってみます。

図のようにリクエストの種類を選択して、APIのURLを入力します。次に画面からヘッダー情報やデータを入力します。ヘッダー情報は補完も効くので、入力しやすくなっています。

Postmanでリクエストを実行する例

あとは「Send」でリクエストを実行するだけです。上図の右下のように、APIサーバーからのレスポンスの内容を確認できます。やっていることはcurlコマンドと同じですが、画面から操作できるので便利です。

また次の図のように、実行したリクエストをcurlコマンドの形式で表示できます:

実行したリクエストのcurlコマンド形式で表示する

つまり:

1. Postmanで実行する
2. ドキュメントを書く用にcurlコマンドを取得する

という使い方ができます。これはとても役に立つ機能なので、ぜひ覚えておいてください。

Postmanは他にもいろんな機能がありますが、基本的にはこの使い方だけでいいです。試してみてください。

おわりに

APIの動作確認にはcurlコマンドとPostmanを使うやり方があります。この2つは開発をする上で何度も使うことになります。この記事が開発・学習の役に立てばうれしいです。