curlでJSONボディをPOST送信

curlでJSONをPOST送信する

JSONボディを伴うPOSTリクエストは、現代のAPI通信の基盤です。curlを使えば、あらゆるエンドポイントに構造化データを簡単に送信できます。

基本的なJSON POST

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

-X POST フラグでHTTPメソッドを設定し、-H でContent-Typeヘッダーを追加し、-d でリクエストボディを指定します。

ファイルからJSONを読み込む

大きなペイロードの場合、@ プレフィックスを使ってファイルからJSONボディを読み込みます:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

--jsonフラグの使用（curl 7.82以降）

最新版のcurlには、Content-TypeヘッダーとAcceptヘッダーを自動設定する --json ショートカットがあります:

curl --json '{"name": "Alice"}' https://api.example.com/users

これは -H "Content-Type: application/json"、-H "Accept: application/json"、-d をすべて同時に設定するのと同等です。

エスケープとクォート

シェルスクリプトでJSONを扱う際、クォートの処理が複雑になることがあります。シェルの変数展開を避けるため、JSON文字列をシングルクォートで囲みましょう:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"count": 42, "active": true, "tags": ["admin", "user"]}'

シェル変数を含める必要がある場合は、ダブルクォートに切り替えて内部のクォートをエスケープします:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$USER_NAME\"}"

リクエストの検証

開発中は、POSTリクエストと -v（verbose）を組み合わせて、ヘッダーやステータスコードを含むリクエスト・レスポンスの全体を確認しましょう。送信前にJSONの整合性を検証するには、jq にパイプして確認するのが有効です。