ソフトウェアを開発していると、APIを実行する機会があると思います。ただ、初めてAPIに触れるときや、久しぶりにAPIを実行するときなどは、やり方が分からないかもしれません。
私はウェブエンジニアとして、APIを用いた開発に携わってきました。この経験をもとに、この記事ではAPIの動作を確認する代表的な方法として、①curlコマンドを実行する方法と、②Postmanというツールを使う方法について解説します。
この記事を読むことで、ソフトウェアの開発に必要なcurlコマンドの基本知識が身につきます。また、Postmanという「使いこなせると開発効率が上がるツール」の使い方が分かります。参考になればうれしいです。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
APIの仕組み
まずはじめに、APIとはそもそもどのような仕組みなのか?について説明します。APIはApplication Programming Interfaceの略で、他のアプリとのやりとりを行うための窓口のことをいいます。
APIにリクエストを送ることで、アプリケーションを操作したり、何かしらのデータを受け取ることができます。世の中にはいろんなAPIが公開されていて、例えばGitHubやTwitterも、APIを通してユーザーに操作を許可したり、情報を提供したりしています。
HTTPメッセージ
このAPIへのリクエストは、「HTTPメッセージ」というものでやりとりされます。APIへのリクエストであるリクエストメッセージと、APIからの応答であるレスポンスメッセージの2つからなります。
この2つのメッセージについて、概要図を次に示します。APIを使いたいクライアントと、APIを提供するウェブサーバーとの間で、図のようなHTTPメッセージがやりとりされます。
図の左側のように、クライアントからAPIサーバーに対してリクエストメッセージを送ると、サーバー上で何らかの処理が行われます。結果として、図の右側のようにサーバーからクライアントにレスポンスメッセージが返ってきます。
APIの動作を確認する方法
この記事の目的は「APIの動作を確認する方法」を学ぶことです。言いかえると、上の図において「どのようなリクエストメッセージを、どうやって送るか」となります。
この方法が、curlコマンドやPostmanというツールになります。
例えばcurlコマンドはどのようなリクエストを送るかを指定でき、あわせてヘッダー情報を設定できます。またレスポンスとしてどのようなステータスが返ってきたか、どのようなヘッダー情報が設定されているか、などを表示できます。
コマンドラインから動作を確認する方法がcurlコマンドで、GUIから操作する方法がPostmanです。他にもやり方はありますが、この2つが代表的な方法になります。この2つについて、次に解説していきます。
① curlコマンド
curlは、HTTPなどのさまざまなプロトコルを用いてデータを転送するライブラリやコマンドラインツールを提供するプロジェクトです。「カール」と発音します。
curlプロジェクトは、次の2つを提供しています。
- ライブラリのlibcurl
- コマンドラインツールの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コマンドが入っていない場合、あるいは別のバージョンを使いたい場合は、公式サイトにある手順でインストールしてください。
動作環境
この記事の内容は、次の各バージョンで動作を確認しています。
項目 | バージョン |
---|---|
macOS | 11.6 |
curl | 7.64.1 |
curlコマンドの使い方
それでは、curlコマンドの使い方について説明します。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コマンドの例
次に、よく使う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 }
ここでは、APIサーバーとしてJSONPlaceholderを使っています。JSONPlaceholderは、JSON形式のテストデータを返すAPIを無料で提供しています。GETだけでなくPOSTやPUT、DELETEなどのメソッドに対応しているため、curlコマンドなどの動作を確認するときに便利なサービスです。
② Postman
次に、Postmanの使い方について説明します。
上で説明したcurlコマンドはコマンドラインツールで、ターミナル.appなどのアプリケーションからコマンドとして実行します。ただ、GUIから気軽に操作したいときもあるかもしれません。このときに役立つ、APIの動作確認ができる代表的なGUIツールがPostmanになります。
Postmanは無料で利用できて、リクエストを保存して後から実行することができます。実行履歴も表示してくれたりと、APIの動作確認にとても役立つツールです。
Postmanのインストール
Postmanは公式サイトからダウンロードできます。公式サイトの内容にしたがうことでインストールできます。
動作環境
この記事の内容は、次の各バージョンで動作を確認しています。
項目 | バージョン |
---|---|
macOS | 11.6 |
Postman | 9.0.3 |
Postmanの使用例
それでは、Postmanの使い方について説明します。ここでは例として、前述したcurlコマンドの「ヘッダーとデータを指定してPOSTリクエストする」例を紹介します。
次の図のようにリクエストの種類を選択して、APIのURLを入力します。次に画面からヘッダー情報やデータなどを入力します。ヘッダー情報は補完も効くので、入力しやすくなっています。
あとは「Send」ボタンでリクエストを実行するだけです。上の図の右下のように、APIサーバーからのレスポンスの内容を確認することができます。やっていることはcurlコマンドと同じですが、画面から操作できるので便利だと思います。
また次の図のように、実行したリクエストをcurlコマンドの形式で表示することもできます。
つまり、次のような使い方ができます。
- Postmanで実行する
- 開発ドキュメントを書くためにcurlコマンドを取得する
これはとても役に立つ機能なので、ぜひ試してみてください。Postmanは他にもいろんな機能がありますが、基本的にはこの使い方だけでいいと思います。
まとめ
APIの動作を確認する方法として、curlコマンドとPostmanの2つを使うやり方があります。この2つはソフトウェアを開発する上で何度も使うことになります。この記事が開発や学習の役に立てばうれしいです。