プロダクト開発

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

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

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

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

具体的には:

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

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

著者
ぜに/Hiroki Zenigami

Webエンジニア&プロダクトマネージャ←プログラミング教育で起業←東大院←熊本高専。 共著に「現場で使えるRuby on Rails 5」。

目次

APIの仕組み

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

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

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

HTTPメッセージ

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

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

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

動作環境

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

項目バージョン
macOS11.6
curl7.64.1

curlコマンドの使い方

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

$ curl [options...] <url>

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

$ curl https://example.com

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

オプションオプション概要
-X--requestリクエストの種類を指定する
-H--headerリクエストヘッダーを追加する
-d--dataPOSTリクエストで送信するデータを指定する
-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コマンドの例

次に、よく使う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は公式サイトからダウンロードできます。公式サイトにしたがえばインストールできます。

動作環境

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

項目バージョン
macOS11.6
Postman9.0.3

Postmanの使用例

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

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

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

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

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

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

つまり:

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

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

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

おわりに

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

著者
ぜに/Hiroki Zenigami

Webエンジニア&プロダクトマネージャ←プログラミング教育で起業←東大院←熊本高専。 共著に「現場で使えるRuby on Rails 5」。

関連記事関連書籍人気記事
applis
エンジニアとしてのんびり暮らす
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは下記よりお願いいたします
お問い合わせ
© applis