この記事では、APIの動作を確認する方法として①curlコマンドを実行する方法と、②Postmanというツールを使う方法を解説します。
APIを用いた開発・学習をするとき、APIの動作を確認することがあります。初めてAPIを触れるときなどは、やり方がわからないと思います。
私も初めは「ドキュメントに出てくるcurlって何?」と思っていました。この記事を読むことで、APIの動作を確認する方法を学ぶことができます。
具体的には:
私はWebエンジニアとしてAPIを用いた開発に携わってきました。最近もcurlコマンドやPostmanを使う機会があり、自分へのメモも兼ねてこの記事を書いています。
まず初めに「APIとはそもそもどんな仕組みなのか」を整理します。APIはApplication Programming Interfaceの略で、他のアプリとのやりとりを行うための窓口のことをいいます。
APIにリクエストを送ることで、アプリケーションを操作したり、何かしらのデータを受け取ることができます。
世の中にはいろんなAPIが公開されています。例えばGitHubやTwitterも、APIを通して操作したり情報を取得したりできます。
このAPIへのリクエストは、“HTTPメッセージ”というものでやりとりされます。APIへのリクエストであるリクエストメッセージと、APIからの応答であるレスポンスメッセージからなります。
概要図を次に示します。APIを使いたいクライアントと、APIを提供するWebサーバーとの間で、図のようなHTTPメッセージがやりとりされます:
HTTPメッセージの概要
図の左側のように、クライアントからAPIサーバーに対してリクエストメッセージを送ると、サーバー上で何らかの処理がされます。結果として、図の右側のようにサーバーからクライアントにレスポンスが返ってきます。
この記事の目的は「APIの動作を確認する方法」を学ぶことです。言いかえると、上図において「どのようなリクエストメッセージを、どうやって送るか」です。
この方法がcurlコマンドやPostmanというツールになります。
例えばcurlコマンドはどんなリクエストを送るかを指定でき、あわせてヘッダー情報を設定できます。またレスポンスとしてどんなステータスが返ってきたか、どんなヘッダー情報が設定されているかなどを表示できます。
コマンドラインから動作を確認する方法がcurlコマンドで、GUIから操作する方法がPostmanです。他にもやり方はありますが、この2つが代表的な方法になります。この2つについて解説していきます。
curlはHTTPなどさまざまなプロトコルを用いてデータを転送するライブラリ・コマンドラインツールを提供するプロジェクトです。「カール」と発音します。
curlプロジェクトが提供しているのは次の2つです:
この記事で解説するのは2のcurlコマンドになります。curlコマンドは内部でlibcurlを用いています。プロトコルはHTTP以外にもHTTPやFTP、IMAP、POP3、SMTPなどに対応していて、いろんなツールでlibcurlが採用されています。
macOSや最近のLinuxディストリビューションには標準でcurlコマンドが入っています。Windowsも、10のVer.1808からcurl.exeというコマンドが標準で付属されているようです。
curlコマンドが入っていない場合、あるいは別のバージョンを使いたい場合は公式サイトにある手順でインストールすればいいです。
この記事の内容は、次の各バージョンで動作を確認しています:
項目 | バージョン |
---|---|
macOS | 11.6 |
curl | 7.64.1 |
curlコマンドの基本形は次の通りです:
$ curl [options...] <url>
オプションがない場合、例えば次のコマンドの場合はURLに対してGETリクエストを送ります。この場合、結果として内容、つまりHTMLファイルが表示されます:
$ curl https://example.com
curlコマンドでよく使うオプションを表でまとめます:
オプション | オプション | 概要 |
---|---|---|
-X | --request | リクエストの種類を指定する |
-H | --header | リクエストヘッダーを追加する |
-d | --data | POSTリクエストで送信するデータを指定する |
-F | --form | ファイルをアップロードする |
-L | --location | リダイレクト先までアクセスする |
-u | --user | ユーザー名とパスワードを指定する |
-b | --cookie | 実行時のクッキーを指定する |
-I | --head | レスポンスヘッダーを表示する |
-i | --include | レスポンスヘッダー・内容を表示する |
-v | --verbose | リクエストヘッダー・レスポンスヘッダー・内容を表示する |
-o | --output | ファイル名を指定して保存する |
-O | --remote-name | リクエスト先のファイル名で保存する |
-s | --silent | 実行中のメッセージを表示しない |
-S | --show-error | エラーメッセージを表示する |
-f | --fail | 失敗してもエラーメッセージを表示しない |
-w | --write-out | 出力フォーマットを指定する |
次に、よく使う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
$ 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
}
curlコマンドはコマンドラインツールで、ターミナル.appなどのアプリケーションからコマンドとして実行します。ただ、GUIから気軽に操作したいときもあると思います。APIの動作確認ができる代表的なGUIツールがPostmanです。
Postmanは無料で利用でき、リクエストを保存して後から実行することができます。実行履歴も表示してくれたりと、APIの動作確認にとても役立つツールです。
Postmanは公式サイトからダウンロードできます。公式サイトにしたがえばインストールできます。
この記事の内容は、次の各バージョンで動作を確認しています:
項目 | バージョン |
---|---|
macOS | 11.6 |
Postman | 9.0.3 |
例として、前述したcurlコマンドの「ヘッダーとデータを指定してPOSTリクエストする」例をやってみます。
図のようにリクエストの種類を選択して、APIのURLを入力します。次に画面からヘッダー情報やデータを入力します。ヘッダー情報は補完も効くので、入力しやすくなっています。
Postmanでリクエストを実行する例
あとは「Send」でリクエストを実行するだけです。上図の右下のように、APIサーバーからのレスポンスの内容を確認できます。やっていることはcurlコマンドと同じですが、画面から操作できるので便利です。
また次の図のように、実行したリクエストをcurlコマンドの形式で表示できます:
実行したリクエストのcurlコマンド形式で表示する
つまり:
という使い方ができます。これはとても役に立つ機能なので、ぜひ覚えておいてください。
Postmanは他にもいろんな機能がありますが、基本的にはこの使い方だけでいいです。試してみてください。
APIの動作確認にはcurlコマンドとPostmanを使うやり方があります。この2つは開発をする上で何度も使うことになります。この記事が開発・学習の役に立てばうれしいです。