APIの動作確認やちょっとした疎通確認では、curlをよく使います。使うたびにオプションを調べ直すことが多いので、目的別に整理しました。
基本構文
curl [オプション] URL
主なオプション一覧
| オプション | 意味・使い方例 |
|---|---|
-X |
HTTPメソッドを指定する（例：-X POST） |
-H |
ヘッダーを追加する（例：-H "Content-Type: application/json"） |
-d |
リクエストボディ（データ）を送る。指定すると自動的にPOSTになる |
-i |
レスポンスをヘッダー込みで表示する |
-I |
HEADリクエスト。ヘッダーのみ取得しボディは取得しない |
-s |
進捗などを表示しない（サイレント） |
-sS |
サイレント＋エラー時だけ表示（実務では-s単体より推奨） |
-o |
出力ファイル名を指定する（例：-o result.json） |
-O |
レスポンスをURL末尾と同じファイル名で保存する |
-L |
リダイレクトを自動で追いかける |
-v |
通信の詳細（リクエスト/レスポンスヘッダー含む）を表示する。デバッグ時に必須 |
-k |
SSL証明書検証をスキップする（自己署名証明書のローカル環境などで使用。中間者攻撃に弱くなるため本番では避ける） |
-F |
multipart/form-dataで送信する（ファイルアップロード時） |
-u |
Basic認証。例：-u user:password
|
-w |
レスポンス情報をフォーマット出力する。例：-w "%{http_code}\n"
|
-G |
-dのデータをクエリパラメータとしてGETに付与する |
-b |
クッキーを送信する。例：-b "session_id=abc123"
|
-c |
レスポンスのSet-Cookieをファイルに保存する |
-A |
User-Agentを指定する。例：-A "MyApp/1.0"
|
-T |
指定したファイルをそのままアップロードする（PUTなどで使用） |
-x |
プロキシ経由でアクセスする。例：-x http://proxy.example.com:8080
|
-m / --max-time
|
リクエスト全体のタイムアウト秒数を指定する |
--connect-timeout |
接続確立までのタイムアウト秒数を指定する |
--compressed |
gzip圧縮されたレスポンスを自動展開する |
よく使うパターン集
1. GET（デフォルト）
curl https://example.com/api/users
2. POST（JSON送信）
curl -X POST https://example.com/api/users \
-H "Content-Type: application/json" \
-d '{"name":"Ume", "email":"ume@example.com"}'
3. PUT（データ更新）
curl -X PUT https://example.com/api/users/123 \
-H "Content-Type: application/json" \
-d '{"email":"new@example.com"}'
4. DELETE（データ削除）
curl -X DELETE https://example.com/api/users/123
5. 認証付き（Bearerトークン）
curl https://example.com/api/private \
-H "Authorization: Bearer YOUR_TOKEN"
6. ファイルをダウンロード
curl -o image.png https://example.com/logo.png
# URLと同じファイル名で保存したい場合
curl -O https://example.com/logo.png
7. ファイルアップロード（multipart）
curl -X POST https://example.com/upload \
-F "file=@./image.png"
8. ステータスコードだけ確認したいとき
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/api/health
9. クエリパラメータをまとめて付与する（-G）
curl -G https://example.com/search \
-d "q=curl" \
-d "page=1"
# → https://example.com/search?q=curl&page=1 と同じ結果になる
10. クッキーを送受信する
# ログインしてクッキーを保存する
curl -c cookies.txt https://example.com/login \
-d "user=ume&pass=xxxx"
# 保存したクッキーを使って別のリクエストを送る
curl -b cookies.txt https://example.com/api/mypage
11. タイムアウトを指定する
curl --connect-timeout 5 -m 10 https://example.com
接続確立までを--connect-timeout、リクエスト全体を-mで分けて指定できます。API疎通が不安定な環境の切り分けに便利です。
-Xと-dの関係で迷いやすい点
-dを指定すると、-Xを書かなくても自動的にPOSTになります。逆に-X GETと-dを組み合わせると、GETメソッドのままボディ付きリクエストが送られます。文法上は許容されていますが、サーバーやプロキシによっては無視・拒否されることがあるため、意図せずこの組み合わせにならないよう注意します。
REST APIテストでの使い方まとめ
| 操作 | curl コマンド例 |
|---|---|
| データ取得（GET） | curl https://api.example.com/items |
| データ作成（POST） | curl -X POST -H "Content-Type: application/json" -d '{"name":"foo"}' https://api.example.com/items |
| データ更新（PUT） | curl -X PUT -d '{"name":"bar"}' https://api.example.com/items/123 |
| データ削除（DELETE） | curl -X DELETE https://api.example.com/items/123 |
よくあるエラーと対処法
| エラー内容 | 対処 |
|---|---|
401 / 403 |
Authorizationヘッダーの有無・トークンの期限を確認する |
415 Unsupported Media Type |
Content-Typeがボディの形式と一致しているか確認する |
SSL certificate problem |
証明書が正しいか確認する。検証を一時的にスキップするなら-k（本番では非推奨） |
curl: (7) Failed to connect |
URLやポート番号のミス、サーバー側の起動状況、VPN/プロキシ設定を確認する |
curl: (28) Operation timed out |
--connect-timeoutや-mで切り分け、ネットワーク経路やサーバー負荷を確認する |
まとめ（主要オプション早見表）
-
-X→ メソッド指定（GET, POST, PUT など） -
-H→ ヘッダー追加（Content-Type や Authorization） -
-d→ データを送る（JSONなど、自動的にPOSTになる） -
-i/-I→ ヘッダー込み表示 / ヘッダーのみ取得 -
-o/-O→ 任意のファイル名で保存 / URLと同じファイル名で保存 -
-L→ リダイレクトを追いかける -
-v→ デバッグ用の詳細ログ -
-F→ マルチパートアップロード -
-w→ レスポンス情報のフォーマット出力 -
-b/-c→ クッキーの送信 / 保存 -
-m/--connect-timeout→ タイムアウトの切り分け