はじめに
APIの解説でよく見る、curlから始まる1行。最初は「どこに入力するの?」「実行すると何が起きるの?」と感じるかもしれません。
curlは、URLを指定してデータを送受信できるコマンドラインツールです。この記事では、練習用の公開APIを使って、取得・送信・認証ヘッダーの基本を整理します。
目的はコマンドを暗記することではなく、 「どこへ、何を依頼して、何が返ったか」を読めるようになること です。
macOSとWindows PowerShellの例を載せます。2026年9月25日にmacOS 26.6.2・curl 8.7.1で主要コマンドを確認しました。Windowsの説明はMicrosoftの公式資料で確認したもので、Windows実機での動作確認はしていません。
1. APIとHTTPを先に整理する
APIは、プログラムの機能やデータを、別のプログラムから使うための取り決めです。APIにはさまざまな種類がありますが、ここではURLへ通信する Web API を扱います。
HTTPは、その通信で使うルールです。HTTPSはHTTPの通信をTLSで保護します。curlは、このルールに沿って依頼を送る道具の1つです。
| 用語 | 役割 | 今回の例 |
|---|---|---|
| URL | 通信先を示す | https://jsonplaceholder.typicode.com/posts/1 |
| メソッド | 何を依頼するかを示す |
GETで取得、POSTでデータを送信 |
| リクエストヘッダー | 依頼に付ける補足情報 | 送信形式、認証情報など |
| リクエストボディ | 送るデータ本体 | 投稿のタイトルと本文など |
| ステータスコード | サーバーが返す処理結果の種類 |
200、201、404など |
| レスポンスボディ | 返ってきたデータ本体 | JSONで表された投稿データ |
POSTはAPIごとに作成・処理の実行などに使われます。「送信したら必ず新規保存される」という共通仕様ではありません。
HTTPの用語・メソッド・ステータスコードの原典は RFC 9110 です。この表と図は、練習用APIに合わせた筆者の整理です。
2. Mac・Windowsでcurlを確認する
Mac:ターミナルで確認
「ターミナル」アプリを開いて入力します。
curl --version
Windows:PowerShellではcurl.exeと書く
PowerShellを開き、次のように入力します。
curl.exe --version
Windows環境でもまずこのコマンドで有無とバージョンを確認します。見つからない場合は curl公式のWindows向け配布案内 を確認してください。
Windows PowerShell 5.1のcurlは、curl本体ではなくInvoke-WebRequestの別名として動く場合があります。混乱を避けるため、この記事ではWindows側を curl.exeに統一 します。
出典:Microsoft Learn:Invoke-WebRequest(Windows PowerShell 5.1)
この記事の--jsonはcurl 7.82.0以降が必要です。古い場合の代替コマンドも後で載せます。シェルの$やPS>といった入力待ち表示は、コマンドの一部ではないため入力しません。
3. まずGETでデータを取得する
練習先は、ダミーデータを返す JSONPlaceholder です。外部の公開サービスなので、機密情報・個人情報・本物の認証情報は送らないでください。
curl --max-time 30 "https://jsonplaceholder.typicode.com/posts/1"
curl.exe --max-time 30 "https://jsonplaceholder.typicode.com/posts/1"
このようにURLだけを指定したHTTPリクエストは、通常GETになります。--max-time 30は処理全体の制限時間を30秒にする指定です。
返り値には、userId、id、title、bodyがあります。これは JSONというデータ形式 です。
{
"userId": 1,
"id": 1,
"title": "投稿のタイトル",
"body": "投稿の本文"
}
{}はオブジェクト、"title"などの左側がキー、右側が値です。文字列は""で囲み、数値は囲みません。最後の項目の後ろにはカンマを付けません。
ヘッダーも見るには-i
curl --max-time 30 -i "https://jsonplaceholder.typicode.com/posts/1"
Windowsでは先頭をcurl.exeに置き換えます。レスポンスの先頭にHTTPステータス、その後にヘッダー、空行を挟んでJSONが表示されます。
小文字の-iは、通常の応答にヘッダーも表示する指定です。大文字の-IはHTTPではHEADリクエストを使う指定で、同じ動作ではありません。
条件を付けて取得する
curl --max-time 30 --get --data-urlencode "userId=1" "https://jsonplaceholder.typicode.com/posts"
--getと--data-urlencodeを組み合わせ、条件をURLのクエリ文字列として送ります。この例ではuserId=1の投稿一覧が返ります。複数件のJSONは[]で囲まれた配列になります。
URLを""で囲む習慣を付けると、&などがシェルの記号として扱われるトラブルも避けやすくなります。
4. JSONファイルをPOSTで送る
MacとWindowsでは、コマンド内の引用符の扱いに違いがあります。最初はJSONを直接1行に埋め込まず、 ファイルに分ける方法 が分かりやすいです。
エディターで次の内容をrequest.jsonとして保存します。文字コードはUTF-8(BOMなし)にし、ターミナルでは保存したフォルダを開いてください。
{
"title": "curl practice",
"body": "hello API",
"userId": 1
}
curl --max-time 30 -i --json "@request.json" "https://jsonplaceholder.typicode.com/posts"
curl.exe --max-time 30 -i --json "@request.json" "https://jsonplaceholder.typicode.com/posts"
@request.jsonはファイルから読み込む指定です。PowerShellで@を特別な記号と解釈させないためにも、引用符を付けます。
--jsonには、次の意味があります。
- ファイルの内容をデータとして送る。
-
Content-Type: application/jsonを付ける。 -
Accept: application/jsonを付ける。 - この使い方では
POSTを使う。-X POSTを重ねる必要はない。
Content-Typeは送るデータの形式、Acceptは受け取りたい形式を伝えます。ただし、相手のAPIが必ず希望どおり返す保証ではありません。また、 curlの--json自体はJSONの構文を検査しません。
JSONPlaceholderでは201 Createdと、送信内容にid: 101を加えたデータが返ります。ただし、 実際にサーバーへ永続保存されるわけではありません。 あくまで作成できたように応答する練習用APIです。
出典:JSONPlaceholder公式ガイド:Creating a resource
実業務のAPIで同じ操作をすると、データ登録・通知・課金などが起きる可能性があります。練習用URLを本番環境のURLへ置き換えて、意味を確認せず実行しないでください。
--jsonが使えない場合
curl --max-time 30 -i -H "Content-Type: application/json" -H "Accept: application/json" --data-binary "@request.json" "https://jsonplaceholder.typicode.com/posts"
Windowsでは先頭をcurl.exeに置き換えます。この例は--jsonがまとめて行う指定を、個別に書いたものです。
5. 認証情報はヘッダーに付ける
APIによっては、誰が利用しているのか、何を許可するかを判断するための資格情報が必要です。
次は 構造だけを示す概念例 です。api.example.comは説明用の架空の接続先、トークンも偽物なので、このコマンドでは利用可能なAPIにアクセスできません。
curl -H "Authorization: Bearer <アクセストークン>" "https://api.example.com/me"
-Hはリクエストヘッダーを追加する指定です。サーバー側はトークンなどを検証し、操作が許可されるか判断します。ヘッダーを書けば自動的に認証が成功するわけではありません。
APIキーを送るヘッダー名や、トークンの取得方法はサービスごとに異なります。APIの公式仕様を確認します。
認証方式の整理は、前の記事で詳しく説明しています。
本物の秘密情報で試す前に
- 公開の練習用APIや、リクエストをそのまま返す確認サービスへ本物のキーを送らない。
- URLのクエリに秘密情報を入れない。記録・共有されやすくなる。
- コマンド履歴、プロセス情報、ログ、スクリーンショット、Gitへの混入に注意する。
- HTTPSを使っても、自分のPC上の履歴や表示内容まで隠れるわけではない。
環境変数などへ移すだけで、あらゆる漏えいを防げるわけではありません。実務ではサービスの推奨方法と組織の秘密情報管理ルールに従います。
6. HTTPエラーとcurlのエラーは別
APIが404を返しても、curl自体は「通信して応答を受け取れた」として終了コード0になることがあります。
たとえば、存在しない投稿を取得します。
curl --max-time 30 -i "https://jsonplaceholder.typicode.com/posts/999999"
echo $?
続けて実行したecho $?は、直前のコマンドの終了コードを表示します。Windows PowerShellでは次のように確認します。
curl.exe --max-time 30 -i "https://jsonplaceholder.typicode.com/posts/999999"
$LASTEXITCODE
HTTPの400以上もコマンドの失敗として扱いたい場合は、--fail-with-bodyを使います。エラー時の本文を残しながら、HTTPエラーを終了コード22として扱います。このオプションはcurl 7.76.0以降です。
curl --max-time 30 --fail-with-body -i "https://jsonplaceholder.typicode.com/posts/999999"
echo $?
出典:curl公式:--fail-with-body、終了コード一覧
| 見えた結果 | 最初に確認すること |
|---|---|
| HTTP 401 | 必要な認証情報がない、または受け入れられない理由をAPI仕様で確認 |
| HTTP 403 | アクセス権限・ポリシーなど、サーバーが拒否した理由を確認 |
| HTTP 404 | URLや対象データのIDを確認。サービスによっては存在を隠すためにも使う |
| HTTP 429 | 利用制限と再試行条件を確認。連打しない |
| HTTP 5xx | サーバー側のエラー。障害情報とAPI側のログを確認 |
| curlの終了コード28 | 制限時間を超過。通信先・ネットワーク・処理時間を確認 |
| curlの終了コード60 | 証明書検証に失敗。PCの時刻、接続先、信頼するCA証明書などを確認 |
証明書エラーを見て、すぐに-kや--insecureを付けるのは避けます。これらは証明書の検証を省略し、安全性を下げるためです。
出典:curl公式:TLS証明書の検証。HTTPステータスの表は RFC 9110 と RFC 6585の429 を基にした筆者の確認手順です。
7. Mac・Windowsで迷いやすい点
| 項目 | macOSのzsh・bash | Windows PowerShell |
|---|---|---|
| 実行名 | curl |
curl.exeを推奨 |
| 直前の終了コード | echo $? |
$LASTEXITCODE |
| 複数行の継続記号 | バックスラッシュ | バッククォート |
| JSONの送信 | ファイルを使うと引用符の混乱を減らせる | 同左。"@request.json"と囲む |
この記事のコマンドは、継続記号を使わない1行形式です。ブラウザーの幅で折り返されて見えても、途中へ手作業で改行を加える必要はありません。WindowsのコマンドプロンプトとPowerShellも別物なので、入力する画面を確認してください。
おわりに
最初は、次の3つを自分の言葉で説明できれば十分です。
-
GETで何を取得したか。 -
POSTでどのJSONファイルを送ったか。 - HTTPステータスとcurlの終了コードがどう違ったか。
まずは練習用APIで-iあり・なしの表示を比べ、次にrequest.jsonのtitleを書き換えて送ってみてください。小さな通信を自分で確かめると、APIの説明やエラーメッセージが読みやすくなります。
Wealthy Designでは、API・クラウドの基礎を、現場で確認しながら使える形で発信しています。会社の取り組みも、よければご覧ください。
AWS・Web開発・AI活用のご相談や、採用・カジュアル面談については、Wealthy Design公式LINEでもお問い合わせいただけます。

