curlコマンドでAPI呼び出し実践：HTTPリクエストの基本から応用まで完全ガイド

curlコマンドを使ってAPIを呼び出す際は、HTTPメソッドとエンドポイントURLを正確に指定し、適切なヘッダーと認証情報を設定することが成功の鍵です。単純なGETリクエストからPOST/PUT/DELETEまで、curlの基本構文をマスターすれば、どんなAPIでも自在に操作できるようになります。

本記事では、curlコマンドによるAPI呼び出しの基本から応用テクニックまで、実務で即座に活用できる具体的な手法を網羅的に解説します。HTTPステータスコードの正しい解釈方法、JSONデータの送受信、認証トークンの扱い方、さらにはデバッグ手法まで、実践的なノウハウを余すところなく紹介します。curlコマンドを使ったAPI連携作業の効率を劇的に向上させたいエンジニア必見の内容です。

目次

curlコマンドの基本構文とインストール方法

curlとは何か：HTTP…

curlは、Command Line URL（コマンドラインURL）の略称で、さまざまなプロトコル（HTTP、HTTPS、FTP、SMTPなど）をサポートしたコマンドラインツールです。API呼び出しにおいては、HTTP/HTTPSプロトコルを使用してサーバーと通信する際に最も一般的に利用されるツールとなっています。

curlの主な特徴は以下の通りです：

  • HTTPメソッド（GET、POST、PUT、DELETE、PATCHなど）を完全にサポート
  • リクエストヘッダーとボディの柔軟な設定が可能
  • 認証情報（Basic認証、Bearerトークン、OAuthなど）の扱いに優れている
  • レスポンスデータの出力形式をカスタマイズ可能
  • Windows、macOS、Linuxなど主要なOSで動作する
  • スクリプトや自動化に適したコマンドラインインターフェース

curlは、API開発者、システムエンジニア、DevOpsエンジニアにとって、APIの動作確認やテスト、自動化スクリプトの作成に欠かせないツールです。特に、GUIツールを使わずにコマンドラインだけでAPIの動作を確認できる点が大きなメリットです。

curlのインストール方法…

curlはほとんどのLinuxディストリビューションとmacOSに標準でインストールされていますが、最新バージョンを使用するためには手動でインストールすることをお勧めします。Windows環境では、公式のインストーラーを使用するか、WSL（Windows Subsystem for Linux）経由でLinux版を利用する方法が一般的です。

OSインストール方法確認コマンド
Linux（Debian/Ubuntu系）sudo apt update && sudo apt install curlcurl –version
Linux（RHEL/CentOS系）sudo yum install curlcurl –version
macOSHomebrew経由：brew install curl
または公式サイトからダウンロード		curl –version
Windows公式サイト（https://curl.se/windows/）からダウンロード
またはWSL経由でLinux版を利用		curl –version

最新バージョンを使用することで、最新のセキュリティ機能やパフォーマンス最適化を享受できます。特に、HTTP/2やHTTP/3のサポート状況を確認する際には、バージョン情報を確認しておくと良いでしょう。

curlの基本構文とオプシ…

curlの基本的な構文は以下の通りです：

curl [options] [URL]

主なオプションは以下の通りです：

オプション説明使用例
-X, –requestHTTPメソッドを指定（GET, POST, PUT, DELETEなど）curl -X POST https://api.example.com/data
-H, –headerリクエストヘッダーを追加curl -H “Content-Type: application/json” https://api.example.com
-d, –dataリクエストボディに送信するデータを指定curl -X POST -d ‘{“name”:”John”}’ https://api.example.com/users
-u, –userBasic認証のユーザー名とパスワードを指定curl -u username:password https://api.example.com
-b, –cookieCookieを送信curl -b “session=abc123” https://api.example.com
-c, –cookie-jar受信したCookieをファイルに保存curl -c cookies.txt https://api.example.com
-v, –verbose詳細なデバッグ情報を出力curl -v https://api.example.com
-i, –includeレスポンスヘッダーを含めて出力curl -i https://api.example.com
-o, –outputレスポンスをファイルに保存curl -o response.json https://api.example.com/data.json
-w, –write-outレスポンス情報をカスタマイズして出力curl -w “%{http_code}” https://api.example.com

これらのオプションを組み合わせることで、さまざまなAPI呼び出しシナリオに対応できます。特に、-v（verbose）オプションは、リクエストとレスポンスの詳細を確認できるため、APIのデバッグに非常に有効です。

curlのバージョン確認と…

curlのバージョンを確認するには、以下のコマンドを実行します：

curl --version

このコマンドを実行すると、curlのバージョン情報だけでなく、サポートされているプロトコルや機能の一覧も表示されます。例えば、以下のような出力が得られます：

curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2 libssh/0.9.6/openssl/zlib nghttp2/1.43.0 librtmp/2.3
Release-Date: 2022-01-05
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM NTLM_WB SPNEGO SSL TLS-SRP UnixSockets zstd

この出力から、HTTP/2やHTTP/3（alt-svc）、圧縮機能（brotli、zstd）などのサポート状況を確認できます。最新の機能を利用するためには、定期的にアップデートすることをお勧めします。

Linux環境でのアップデート方法は以下の通りです：

  • Debian/Ubuntu系：sudo apt update && sudo apt upgrade curl
  • RHEL/CentOS系：sudo yum update curl
  • macOS（Homebrew経由）：brew update && brew upgrade curl

Windows環境では、公式サイトから最新のインストーラーをダウンロードして実行するか、Chocolateyパッケージマネージャーを使用してアップデートできます。

GETリクエストでデータを取得する基本操作

GETリクエストの基本構文…

GETリクエストは、サーバーからデータを取得する際に使用されるHTTPメソッドです。curlを使ったGETリクエストの基本的な構文は以下の通りです：

curl [URL]

例えば、以下のようなコマンドを実行すると、指定したURLからデータを取得できます：

curl https://jsonplaceholder.typicode.com/posts/1

このコマンドを実行すると、以下のようなJSONレスポンスが返されます：

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

GETリクエストでは、URLにクエリパラメータを追加して、特定の条件でデータを取得することもできます。例えば、以下のようなコマンドを実行すると、userIdが1の投稿を取得できます：

curl "https://jsonplaceholder.typicode.com/posts?userId=1"

クエリパラメータを含むURLをコマンドラインで実行する際は、ダブルクォーテーションで囲むことをお勧めします。これは、シェルによって特殊文字が解釈されるのを防ぐためです。

レスポンスの出力形式を制御…

curlのデフォルトの出力形式は、レスポンスボディのみが表示されます。しかし、APIのデバッグや処理においては、レスポンスヘッダーやステータスコード、実行時間などの情報も重要です。これらの情報を表示するためのオプションを紹介します。

レスポンスヘッダーを含める（-iオプション）

レスポンスヘッダーを含めて出力するには、-iオプションを使用します：

curl -i https://jsonplaceholder.typicode.com/posts/1

このコマンドを実行すると、以下のような出力が得られます：

HTTP/2 200
date: Mon, 15 Apr 2024 12:34:56 GMT
content-type: application/json; charset=utf-8
content-length: 292
x-powered-by: Express
etag: W/"124-..."
cache-control: public, max-age=14400
vary: Origin, Accept-Encoding
{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

レスポンスヘッダーには、HTTPステータスコード（200 OK）、Content-Type、Content-Length、Cache-Controlなどの重要な情報が含まれています。これらの情報は、APIの動作を理解する上で非常に重要です。

レスポンスヘッダーのみを表示（-Iオプション）

レスポンスボディを表示せず、ヘッダーのみを表示するには、-Iオプション（大文字のアイ）を使用します：

curl -I https://jsonplaceholder.typicode.com/posts/1

このコマンドを実行すると、以下のような出力が得られます：

HTTP/2 200
date: Mon, 15 Apr 2024 12:34:56 GMT
content-type: application/json; charset=utf-8
content-length: 292
x-powered-by: Express
etag: W/"124-..."
cache-control: public, max-age=14400
vary: Origin, Accept-Encoding

このオプションは、HEADリクエストと同様に動作し、サーバーのヘッダー情報のみを取得できます。主に、サーバーの状態を確認する際に使用されます。

レスポンスをファイルに保存（-oオプション）

レスポンスをファイルに保存するには、-oオプションを使用します：

curl -o response.json https://jsonplaceholder.typicode.com/posts/1

このコマンドを実行すると、レスポンスがresponse.jsonというファイルに保存されます。ファイルに保存することで、後からデータを解析したり、別のツールで処理したりすることができます。

また、-Oオプション（大文字のオー）を使用すると、レスポンスのファイル名をURLのファイル名と同じにすることができます：

curl -O https://jsonplaceholder.typicode.com/posts/1

このコマンドを実行すると、レスポンスがposts/1というファイルに保存されます。

HTTPステータスコードの…

HTTPステータスコードは、サーバーからのレスポンスの状態を示す3桁の数字です。API呼び出しにおいては、ステータスコードを正しく解釈することが、エラーの原因を特定する上で非常に重要です。主なHTTPステータスコードとその意味は以下の通りです：

ステータスコード分類意味一般的な対応
200成功リクエストが成功し、レスポンスが返されたレスポンスボディを処理
201成功リソースが作成された（POSTリクエストの成功時）作成されたリソースのURLを確認
204成功リクエストは成功したが、レスポンスボディはないレスポンスヘッダーを確認
400クライアントエラーリクエストに問題がある（不正なパラメータなど）リクエスト内容を確認
401クライアントエラー認証が必要（ユーザー認証に失敗）認証情報を確認
403クライアントエラーリソースへのアクセスが拒否された権限を確認
404クライアントエラーリソースが見つからないURLやパラメータを確認
405クライアントエラー指定したHTTPメソッドが許可されていない使用するHTTPメソッドを確認
429クライアントエラーリクエストが多すぎる（レート制限）リクエスト回数を減らす
500サーバーエラーサーバー内部でエラーが発生サーバーのログを確認
502サーバーエラーゲートウェイまたはプロキシでエラーが発生ネットワークやプロキシを確認
503サーバーエラーサービスが一時的に利用できないサービスの状態を確認
504サーバーエラーゲートウェイタイムアウトサーバーの応答時間を確認

curlを使ってAPI呼び出しを行う際には、レスポンスのステータスコードを確認することが非常に重要です。例えば、以下のコマンドを実行すると、ステータスコードのみを出力できます：

curl -s -o /dev/null -w "%{http_code}" https://jsonplaceholder.typicode.com/posts/1

このコマンドを実行すると、レスポンスのステータスコード（例：200）のみが出力されます。-sオプションはサイレントモード（進捗表示を非表示）、-o /dev/nullはレスポンスボディを/dev/nullに送信（破棄）、-w “%{http_code}”はステータスコードを出力するという設定です。

ステータスコードを確認することで、API呼び出しが成功したかどうか、あるいはどのようなエラーが発生したかを迅速に判断できます。

JSONデータのフォーマッ…

APIから返されるJSONデータは、通常は1行で出力されますが、人間が読みやすいように整形することができます。そのために、jqというコマンドラインツールを使用します。

jqは、JSONデータを解析・整形するための軽量なコマンドラインツールで、以下のようにインストールできます：

  • Linux（Debian/Ubuntu系）：sudo apt install jq
  • Linux（RHEL/CentOS系）：sudo yum install jq
  • macOS：brew install jq
  • Windows：公式サイト（https://stedolan.github.io/jq/）からダウンロード

jqを使ってJSONデータを整形するには、以下のように実行します：

curl https://jsonplaceholder.typicode.com/posts/1 | jq

このコマンドを実行すると、以下のような整形されたJSONが出力されます：

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

jqを使うことで、JSONデータを視覚的に確認しやすくなり、APIのレスポンスを理解する上で非常に有効です。また、jqを使って特定のフィールドのみを抽出することもできます：

curl https://jsonplaceholder.typicode.com/posts/1 | jq '.title'

このコマンドを実行すると、タイトルのみが出力されます：

"sunt aut facere repellat provident occaecati excepturi optio reprehenderit"

jqは、API開発において非常に強力なツールであり、curlと組み合わせることで、APIのテストやデバッグを効率的に行うことができます。

POST/PUT/DELETEでデータを操作する応用テクニック

POSTリクエストでデータ…

POSTリクエストは、サーバーに新しいリソースを作成する際に使用されるHTTPメソッドです。curlを使ったPOSTリクエストの基本的な構文は以下の通りです：

curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' [URL]

例えば、以下のコマンドを実行すると、新しいユーザーを作成できます：

curl -X POST -H "Content-Type: application/json" -d '{"name":"John Doe", "email":"john@example.com"}' https://jsonplaceholder.typicode.com/users

このコマンドを実行すると、以下のようなレスポンスが返されます：

{
  "name": "John Doe",
  "email": "john@example.com",
  "id": 11
}

POSTリクエストでは、以下の点に注意する必要があります：

  1. Content-Typeヘッダーをapplication/jsonに設定する
  2. リクエストボディにJSON形式のデータを指定する
  3. -X POSTオプションを明示的に指定する（省略可能な場合もあるが、明示することを推奨）

リクエストボディにJSONデータを指定する際は、シングルクォーテーションで囲むことをお勧めします。これは、ダブルクォーテーションがJSON構文に使用されるためです。

PUTリクエストでデータを…

PUTリクエストは、既存のリソースを完全に置き換える際に使用されるHTTPメソッドです。curlを使ったPUTリクエストの基本的な構文は以下の通りです：

curl -X PUT -H "Content-Type: application/json" -d '{"key":"updated_value"}' [URL]

例えば、以下のコマンドを実行すると、IDが1のユーザー情報を更新できます：

curl -X PUT -H "Content-Type: application/json" -d '{"name":"John Updated", "email":"john.updated@example.com"}' https://jsonplaceholder.typicode.com/users/1

このコマンドを実行すると、以下のようなレスポンスが返されます：

{
  "id": 1,
  "name": "John Updated",
  "email": "john.updated@example.com",
  "phone": "1-770-736-8031 x56442",
  "website": "hildegard.org"
}

PUTリクエストでは、以下の点に注意する必要があります：

  1. リソースのIDを含む完全なURLを指定する
  2. リクエストボディに更新後のデータを完全に含める
  3. Content-Typeヘッダーをapplication/jsonに設定する

PUTリクエストは、既存のリソースを完全に置き換えるため、リクエストボディにはリソースの全てのフィールドを含める必要があります。一部のフィールドのみを更新したい場合は、PATCHリクエストを使用します。

DELETEリクエストでデ…

DELETEリクエストは、既存のリソースを削除する際に使用されるHTTPメソッドです。curlを使ったDELETEリクエストの基本的な構文は以下の通りです：

curl -X DELETE [URL]

例えば、以下のコマンドを実行すると、IDが1のユーザーを削除できます：

curl -X DELETE https://jsonplaceholder.typicode.com/users/1

このコマンドを実行すると、以下のようなレスポンスが返されます：

{}

DELETEリクエストでは、以下の点に注意する必要があります：

  1. 削除対象のリソースのIDを含む完全なURLを指定する
  2. リクエストボディは通常不要（ただし、一部のAPIでは必要な場合もある）
  3. 削除が成功すると、多くの場合204 No Contentステータスコードが返される

DELETEリクエストを実行した際のレスポンスは、APIによって異なります。一部のAPIでは、削除されたリソースの情報が返される場合もあります。レスポンスのステータスコードを確認することで、削除が成功したかどうかを判断できます。

リクエストボディの種類とC…

API呼び出しにおいて、リクエストボディの種類とContent-Typeヘッダーの設定は非常に重要です。主なContent-Typeとその対応するデータ形式は以下の通りです：

XML形式
Content-Typeデータ形式使用例
application/jsonJSON形式curl -H “Content-Type: application/json” -d ‘{“key”:”value”}’ [URL]
application/x-www-form-urlencodedURLエンコード形式curl -H “Content-Type: application/x-www-form-urlencoded” -d “key=value” [URL]
multipart/form-dataファイルアップロードなどcurl -H “Content-Type: multipart/form-data” -F “file=@test.jpg” [URL]
text/plainプレーンテキストcurl -H “Content-Type: text/plain” -d “plain text” [URL]
application/xmlcurl -H “Content-Type: application/xml” -d ‘<key>value</key>’ [URL]

最も一般的に使用されるContent-Typeはapplication/jsonです。JSON形式のデータは、人間が読みやすく、機械的な処理にも適しているため、API呼び出しにおいてデファクトスタンダードとなっています。

URLエンコード形式（application/x-www-form-urlencoded）は、フォームデータの送信などに使用されます。例えば、以下のようなコマンドを実行すると、フォームデータを送信できます：

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "name=John&email=john@example.com" https://example.com/api

ファイルアップロードなど、バイナリデータを送信する際には、multipart/form-data形式を使用します。例えば、以下のようなコマンドを実行すると、ファイルをアップロードできます：

curl -X POST -H "Content-Type: multipart/form-data" -F "file=@test.jpg" https://example.com/upload

Content-Typeの設定を間違えると、API側でリクエストを正しく処理できず、エラーが発生する可能性があります。APIのドキュメントを確認して、適切なContent-Typeを設定するようにしましょう。

リクエストボディにファイル…

curlを使って、リクエストボディにファイルの内容を使用することができます。これは、大量のデータや構造化されたデータを扱う際に非常に便利です。例えば、以下のようなコマンドを実行すると、ファイルの内容をリクエストボディとして送信できます：

curl -X POST -H "Content-Type: application/json" --data-binary "@data.json" https://example.com/api

このコマンドでは、–data-binaryオプションを使用して、ファイルの内容をリクエストボディとして送信しています。@data.jsonという形式で

【編集・制作ポリシー】
本記事はRoute Bloom編集部が各ベンダー公式ドキュメント・エンジニア監修をもとに作成しています。インフラ・クラウド構築は環境により異なります。本番環境への適用前に必ずテストを実施してください。情報の正確性には万全を期していますが、最新情報は各公式ドキュメントをご確認ください。
ABOUT ME
たから
サラリーマンをしながら開業して経営やってます。 今年、本業で独立・別事業を起業予定です。 ◆経験：IT講師/インフラエンジニア/PM/マネジメント/採用/運用・保守・構築・設計 ◆取得資格：CCNA/CCNP/LPIC-1/AZ-900/FE/サーティファイC言語 ◆サイドビジネス：アパレル事業/複数のWEBメディアを運営