curlコマンドでWebAPIを操る

curlコマンドとは

curl（Client URL）は、様々なプロトコルを使用してデータを転送するための強力なコマンドラインツールですね。

特にWeb開発では、APIのテストやデバッグ、ファイルのダウンロードなど、さまざまな場面で活躍します。今回は、curlを使ってWebAPIを自在に操作する方法を一緒に学んでいきましょう！

基本的な使い方

シンプルなGETリクエスト

まずは、一番基本的なGETリクエストから始めましょう。Webページの内容を取得するシンプルな例です：

# URLの内容を取得
$ curl https://example.com

# ヘッダー情報も表示
$ curl -i https://example.com

# ヘッダー情報のみ表示
$ curl -I https://example.com

💡 ポイント: -iオプションでヘッダーとボディ両方、-Iオプションでヘッダーのみを確認できます。APIのレスポンスを確認する時に便利ですね！

ファイルのダウンロード

curlはファイルのダウンロードにもよく使われます。オプションの使い分けを覚えておきましょう：

# ファイルをダウンロード（ファイル名を指定）
$ curl -o myfile.zip https://example.com/file.zip

# 元のファイル名でダウンロード
$ curl -O https://example.com/file.zip

# プログレスバーを表示しない（静かなモード）
$ curl -s -O https://example.com/file.zip

# ダウンロードの再開
$ curl -C - -O https://example.com/largefile.zip

🎯 便利なテクニック:

• -o（小文字）でファイル名を指定
• -O（大文字）で元のファイル名を使用
• -C -で途中から再開（大きなファイルに便利！）

HTTPメソッドの使い分け

GETリクエスト

# 基本的なGETリクエスト
$ curl https://api.example.com/users

# クエリパラメータ付き
$ curl "https://api.example.com/users?page=2&limit=10"

# URLエンコードを自動で行う
$ curl -G --data-urlencode "q=hello world" https://api.example.com/search

POSTリクエスト

APIにデータを送信する時は、POSTリクエストを使います。よく使うパターンを見ていきましょう：

# データを送信
$ curl -X POST -d "name=John&age=30" https://api.example.com/users

# JSONデータを送信
$ curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"John","age":30}' \
  https://api.example.com/users

# ファイルからデータを読み込んで送信
$ curl -X POST -H "Content-Type: application/json" \
  -d @data.json \
  https://api.example.com/users

📝 メモ: JSONを送る時は、必ずContent-Type: application/jsonヘッダーを設定しましょう。APIサーバーが正しくデータを解釈するために必要です！

PUT/PATCH/DELETEリクエスト

# PUTリクエスト（全体更新）
$ curl -X PUT -H "Content-Type: application/json" \
  -d '{"name":"Jane","age":25}' \
  https://api.example.com/users/123

# PATCHリクエスト（部分更新）
$ curl -X PATCH -H "Content-Type: application/json" \
  -d '{"age":26}' \
  https://api.example.com/users/123

# DELETEリクエスト
$ curl -X DELETE https://api.example.com/users/123

ヘッダーの操作

カスタムヘッダーの追加

APIとの通信では、カスタムヘッダーがよく使われます。認証情報やメタデータを送る方法を学びましょう：

# 単一のヘッダー
$ curl -H "Authorization: Bearer TOKEN" https://api.example.com/protected

# 複数のヘッダー
$ curl -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Custom-Header: value" \
  https://api.example.com/data

# User-Agentの変更
$ curl -A "MyApp/1.0" https://api.example.com
# または
$ curl -H "User-Agent: MyApp/1.0" https://api.example.com

🔐 セキュリティのポイント: トークンやパスワードはコマンドラインに直接書かず、環境変数やファイルから読み込むようにしましょうね。

レスポンスヘッダーの確認

# ヘッダーとボディを表示
$ curl -i https://api.example.com

# ヘッダーのみ表示
$ curl -I https://api.example.com

# 詳細な通信情報を表示
$ curl -v https://api.example.com

認証の扱い

Basic認証

# ユーザー名とパスワードを指定
$ curl -u username:password https://api.example.com/protected

# パスワードをプロンプトで入力
$ curl -u username https://api.example.com/protected

# Base64エンコードされた認証情報
$ curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/protected

Bearer Token認証

現代のAPIでは、Bearer Token認証がよく使われます。安全な使い方を見ていきましょう：

# APIトークンを使用
$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.example.com/protected/resource

# 環境変数からトークンを読み込む（推奨）
$ curl -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/protected/resource

⚠️ 重要: トークンをコマンド履歴に残さないよう、環境変数を使う習慣をつけましょう！

JSONデータの処理

JSON APIとの対話

REST APIでは、JSON形式でデータをやり取りすることが一般的です。JSONデータの扱い方を見ていきましょう：

# JSONを整形して表示（jqコマンドと組み合わせ）
$ curl -s https://api.example.com/users | jq .

# 特定のフィールドを抽出
$ curl -s https://api.example.com/users | jq '.[].name'

# JSONデータのPOST
$ curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"key":"value"}' \
  https://api.example.com/data

💡 便利なツール: jqコマンドを使うと、JSONを見やすく整形したり、特定のデータを抽出したりできます。jqがない場合は、python3 -m json.toolでも代用できますよ！

複雑なJSONデータの送信

# インラインで複雑なJSON
$ curl -X POST -H "Content-Type: application/json" \
  -d '{
    "user": {
      "name": "John Doe",
      "email": "john@example.com",
      "preferences": {
        "notifications": true,
        "theme": "dark"
      }
    }
  }' \
  https://api.example.com/users

# ファイルから読み込み
$ cat > user.json << EOF
{
  "name": "John Doe",
  "email": "john@example.com"
}
EOF
$ curl -X POST -H "Content-Type: application/json" \
  -d @user.json \
  https://api.example.com/users

ファイルのアップロード

multipart/form-dataでのアップロード

ファイルのアップロードは、Webアプリケーションでよく使う機能です。curlでは-Fオプションを使います：

# 単一ファイルのアップロード
$ curl -X POST -F "file=@/path/to/file.pdf" \
  https://api.example.com/upload

# 複数ファイルのアップロード
$ curl -X POST \
  -F "file1=@file1.jpg" \
  -F "file2=@file2.png" \
  https://api.example.com/upload

# ファイルと追加データ
$ curl -X POST \
  -F "file=@document.pdf" \
  -F "description=Important document" \
  -F "category=reports" \
  https://api.example.com/upload

📦 豆知識: -Fオプションを使うと、curlは自動的にContent-Type: multipart/form-dataを設定します。HTMLフォームと同じ方式でファイルを送信できるんですよ！

高度な使い方

リダイレクトの処理

# リダイレクトに自動的に従う
$ curl -L https://bit.ly/example

# 最大リダイレクト回数を指定
$ curl -L --max-redirs 3 https://example.com

# リダイレクト先を確認
$ curl -I -L https://bit.ly/example

タイムアウトとリトライ

# 接続タイムアウト（秒）
$ curl --connect-timeout 10 https://slow-server.com

# 全体のタイムアウト
$ curl --max-time 30 https://slow-server.com

# リトライ
$ curl --retry 3 --retry-delay 5 https://unstable-server.com

プロキシの使用

# HTTPプロキシ
$ curl -x http://proxy.example.com:8080 https://target.com

# SOCKSプロキシ
$ curl --socks5 localhost:1080 https://target.com

# プロキシ認証
$ curl -x http://user:pass@proxy.example.com:8080 https://target.com

実践的な使用例

REST APIのCRUD操作

#!/bin/bash
# REST API CRUD操作の例

API_BASE="https://jsonplaceholder.typicode.com"

# Create (POST)
echo "=== Creating new post ==="
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"title":"New Post","body":"Content here","userId":1}' \
  "$API_BASE/posts"

# Read (GET)
echo -e "\n\n=== Reading post ==="
curl "$API_BASE/posts/1"

# Update (PUT)
echo -e "\n\n=== Updating post ==="
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"id":1,"title":"Updated Post","body":"Updated content","userId":1}' \
  "$API_BASE/posts/1"

# Delete
echo -e "\n\n=== Deleting post ==="
curl -X DELETE "$API_BASE/posts/1"

API レスポンスの監視

#!/bin/bash
# APIエンドポイントの監視スクリプト

check_api() {
    local url=$1
    local expected_status=${2:-200}
    
    response=$(curl -s -o /dev/null -w "%{http_code}" "$url")
    
    if [ "$response" = "$expected_status" ]; then
        echo "✓ $url is healthy (HTTP $response)"
        return 0
    else
        echo "✗ $url is unhealthy (HTTP $response, expected $expected_status)"
        return 1
    fi
}

# 使用例
check_api "https://api.example.com/health" 200
check_api "https://api.example.com/v1/status" 200

バッチダウンロード

#!/bin/bash
# URLリストからファイルを一括ダウンロード

# URLリストファイル
cat > urls.txt << EOF
https://example.com/file1.pdf
https://example.com/file2.pdf
https://example.com/file3.pdf
EOF

# 並列ダウンロード
cat urls.txt | xargs -P 4 -I {} curl -O {}

# または順次ダウンロード（進捗表示付き）
while read -r url; do
    filename=$(basename "$url")
    echo "Downloading $filename..."
    curl -# -O "$url"
done < urls.txt

デバッグとトラブルシューティング

詳細なデバッグ情報

# 通信の詳細を表示
$ curl -v https://api.example.com

# さらに詳細な情報（SSL/TLS含む）
$ curl -vv https://api.example.com

# リクエスト/レスポンスヘッダーのみ
$ curl -sv https://api.example.com 2>&1 | grep -E "^[<>]"

# 通信内容をファイルに保存
$ curl --trace trace.txt https://api.example.com

SSL/TLS関連

# SSL証明書の検証をスキップ（開発環境のみ）
$ curl -k https://self-signed.example.com

# 特定のCA証明書を使用
$ curl --cacert /path/to/ca.crt https://api.example.com

# クライアント証明書を使用
$ curl --cert client.crt --key client.key https://api.example.com

パフォーマンスの測定

🎮 理解度チェック

Q1: curlでJSONデータをPOSTする時に必要なヘッダーは？

Q2: ファイルを元のファイル名でダウンロードするオプションは？

Q3: curlでファイルをアップロードするオプションは？

応答時間の測定

APIのパフォーマンスを測定したい時は、curlの-wオプションが便利です：

# 各フェーズの時間を測定
$ curl -o /dev/null -s -w "\
namelookup:    %{time_namelookup}s\n\
connect:       %{time_connect}s\n\
appconnect:    %{time_appconnect}s\n\
pretransfer:   %{time_pretransfer}s\n\
redirect:      %{time_redirect}s\n\
starttransfer: %{time_starttransfer}s\n\
total:         %{time_total}s\n" \
https://api.example.com

# 簡易ベンチマーク
$ for i in {1..10}; do
    curl -o /dev/null -s -w "%{time_total}\n" https://api.example.com
done | awk '{sum+=$1} END {print "Average:", sum/NR "s"}'

ベストプラクティス

セキュリティ考慮事項

1. 認証情報の管理

   # 履歴に残さない
   $ curl -u "$(cat ~/.secrets/api_user):$(cat ~/.secrets/api_pass)" \
     https://api.example.com
   
   # 環境変数を使用
   $ export API_TOKEN="your-secret-token"
   $ curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com
   

2. HTTPSの使用

   # 常にHTTPSを使用
   $ curl https://api.example.com  # Good
   $ curl http://api.example.com   # Avoid
   

3. 入力の検証

   # ユーザー入力をエスケープ
   $ user_input="some input"
   $ curl -G --data-urlencode "q=$user_input" https://api.example.com/search
   

エラーハンドリング

#!/bin/bash
# 堅牢なcurlスクリプトの例

api_call() {
    local url=$1
    local method=${2:-GET}
    local data=${3:-}
    
    response=$(curl -s -X "$method" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $API_TOKEN" \
        ${data:+-d "$data"} \
        -w "\n%{http_code}" \
        "$url")
    
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')
    
    if [[ $http_code -ge 200 && $http_code -lt 300 ]]; then
        echo "$body"
        return 0
    else
        echo "Error: HTTP $http_code" >&2
        echo "$body" >&2
        return 1
    fi
}

# 使用例
if result=$(api_call "https://api.example.com/users" "GET"); then
    echo "Success: $result"
else
    echo "Failed to fetch users"
fi

📝 まとめ

今回はcurlコマンドについて学びました！

curlは、Web APIとの対話において欠かせないツールでしたね。今回学んだポイントを振り返っておきましょう：

• GET/POST/PUT/DELETEなど、様々なHTTPメソッドが使える
• -Hオプションでカスタムヘッダーを追加できる
• JSONデータの送受信にはContent-Typeヘッダーが必須
• -O/-oオプションでファイルダウンロードが簡単
• -Fオプションでファイルアップロードができる
• 認証情報は環境変数を使って安全に管理

curlをマスターすることで、APIのテストやデバッグ、自動化スクリプトの作成など、幅広いタスクをコマンドラインから実行できるようになります。

次はgrepで文字列検索をマスターで、APIレスポンスの解析方法を学んでみましょう！