`curl`でAPIのレスポンスヘッダーとボディを分離して確認する

curl

curlはHTTPリクエストを送る際のデファクトスタンダードですが、レスポンスのヘッダー情報とボディを効率的に確認する方法を知っていますか？リクエストヘッダーも含め、必要な情報を素早くキャッチするTipsで、APIデバッグの速度を向上させましょう。

curlでAPIのレスポンスヘッダーとボディを分離して確認する

APIのデバッグや検証では、レスポンスのヘッダー（ステータスコード、Content-Type、Set-Cookieなど）とボディの両方を確認したいことがよくあります。-vオプションは詳細すぎることがあり、-iオプションではヘッダーとボディが混ざって見づらいことがあります。ここでは、これらをより分かりやすく分離して表示する方法を紹介します。

コード例

# 例1: レスポンスヘッダーを標準エラー出力に、ボディを標準出力に
# この方法だと、パイプでjqに渡してもヘッダーが邪魔にならない
curl -D /dev/stderr "https://api.github.com/users/octocat"

# 例2: レスポンスヘッダーをファイルに保存しつつ、ボディを標準出力に
# （例: headers.txt に保存）
curl -D headers.txt "https://api.github.com/users/octocat"

# 例3: ヘッダーとボディを標準出力に、かつステータスコードなどの情報を最後に表示
# -s: サイレントモードでプログレスバーなどを非表示
# -D -: レスポンスヘッダーを標準出力へ（`--dump-header -` と同じ）
# --write-out: 指定した形式で追加情報を出力
curl -s -D - "https://api.github.com/users/octocat" \
  --write-out '\n--- Status: %{http_code} --- Total time: %{time_total}s\n'

# 例4: JSONレスポンスのヘッダーをエラー出力に、ボディをjqで整形して出力
curl -s -D /dev/stderr "https://api.github.com/users/octocat" | jq .name

注意点やおすすめポイント

• -D /dev/stderr を使うと、レスポンスボディが標準出力にのみ流れ、ヘッダー情報は標準エラー出力に分離されます。これにより、パイプで jq や grep などに渡してボディを処理する際に、ヘッダー情報が邪魔になるのを防ぐことができます。
• --write-out オプションは、curlがリクエスト後に様々な情報（HTTPステータスコード、DNS解決時間、転送速度など）を出力するために使えます。これはAPIのパフォーマンス検証や簡単な死活監視にも役立ちます。man curlで--write-outのセクションを見ると、利用可能な変数の一覧を確認できます。
• jqと組み合わせることで、JSON形式のレスポンスボディから特定のデータを抽出する際に、ヘッダー情報とボディの分離が特に役立ち、効率的なデバッグフローを構築できます。