目次

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

本サイトはアフィリエイトプログラムを利用した広告を表示しています

ソフトウェアを開発していると、APIを実行する機会があると思います。ただ、初めてAPIに触れるときや、久しぶりにAPIを実行するときなどは、やり方が分からないかもしれません。

私はウェブエンジニアとして、APIを用いた開発に携わってきました。この経験をもとに、この記事ではAPIの動作を確認する代表的な方法として、①curlコマンドを実行する方法と、②Postmanというツールを使う方法について解説します。

この記事を読むことで、ソフトウェアの開発に必要なcurlコマンドの基本知識が身につきます。また、Postmanという「使いこなせると開発効率が上がるツール」の使い方が分かります。参考になればうれしいです。

著者
Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

テクニカルライティングを学ぶ

わかりやすい文章の書き方が学べる入門をnoteで公開しました。ブログやドキュメントなどを書くときにお役立てください。

APIの仕組み

まずはじめに、APIとはそもそもどのような仕組みなのか?について説明します。APIはApplication Programming Interfaceの略で、他のアプリとのやりとりを行うための窓口のことをいいます。

APIにリクエストを送ることで、アプリケーションを操作したり、何かしらのデータを受け取ることができます。世の中にはいろんなAPIが公開されていて、例えばGitHubやTwitterも、APIを通してユーザーに操作を許可したり、情報を提供したりしています。

HTTPメッセージ

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

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

HTTPメッセージの概要

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

APIの動作を確認する方法

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

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

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

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

スポンサーリンク

① curlコマンド

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

curlプロジェクトは、次の2つを提供しています。

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

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

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

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

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

動作環境

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

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

curlコマンドの使い方

それでは、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コマンドの例をいくつか紹介します。上のオプション一覧とあわせてご確認ください。

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

$ 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
}
JSONPlaceholder

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

スポンサーリンク

② Postman

次に、Postmanの使い方について説明します。

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

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

Postmanのインストール

Postmanは公式サイトからダウンロードできます。公式サイトの内容にしたがうことでインストールできます。

動作環境

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

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

Postmanの使用例

それでは、Postmanの使い方について説明します。ここでは例として、前述したcurlコマンドの「ヘッダーとデータを指定してPOSTリクエストする」例を紹介します。

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

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

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

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

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

つまり、次のような使い方ができます。

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

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

まとめ

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

あわせて読みたい

著者
Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

スポンサーリンク

ブログをはじめよう

技術ブログの始め方を、たくさんの画像で分かりやすく解説しました。これまでブログをやったことがない人でも、エンジニアにとって重要なブログを今日から始められます。

ブログをはじめる