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

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

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

Hiroki Zenigami

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

Follow @zenizh

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

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

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

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

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

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

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

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

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

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

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

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

この2つのうち、この記事で解説するのは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 -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
}

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

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

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

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

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

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

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

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

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

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

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

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

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

プロダクト開発

【2023年】エンジニアの本でおすすめの5冊を紹介します

2023-4-2

働き方

エンジニアの転職で登録したい7つの転職サイトと転職エージェント

2022-12-30

働き方

エンジニアの副業で登録したい5つのサイトやサービス【フリーランス】

2022-12-30