APIテストとデバッグガイド：cURLからオンラインツールまで
開発ツール伊藤 結衣
HTTPリクエストメソッド
| メソッド | 用途 | 冪等性 | 安全性 |
|---|---|---|---|
| GET | リソースの取得 | ✅ | ✅ |
| POST | リソースの作成 | ❌ | ❌ |
| PUT | 全量更新 | ✅ | ❌ |
| PATCH | 部分更新 | ❌ | ❌ |
| DELETE | リソースの削除 | ✅ | ❌ |
| HEAD | ヘッダー情報の取得 | ✅ | ✅ |
| OPTIONS | CORSプリフライト | ✅ | ✅ |
よく使うリクエストヘッダー
| ヘッダー | 説明 | 例 |
|---|---|---|
Content-Type |
リクエストボディの形式 | application/json |
Accept |
期待するレスポンス形式 | application/json |
Authorization |
認証情報 | Bearer token... |
User-Agent |
クライアント識別子 | Mozilla/5.0... |
Cookie |
Cookie | session=abc123 |
X-Request-ID |
リクエスト追跡ID | UUID |
Content-Typeの代表的な値
| 値 | 用途 |
|---|---|
application/json |
JSONデータ |
application/x-www-form-urlencoded |
フォームデータ |
multipart/form-data |
ファイルアップロード |
text/plain |
プレーンテキスト |
text/html |
HTML |
認証方式
1. Bearer Token（最も一般的）
# cURL
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
https://api.example.com/users
# JavaScript
fetch('https://api.example.com/users', {
headers: {
'Authorization': 'Bearer eyJhbGciOiJIUzI1NiJ9...',
},
});
2. Basic認証
# cURL（自動エンコード）
curl -u username:password https://api.example.com/users
# 手動エンコード
# Base64("username:password") = "dXNlcm5hbWU6cGFzc3dvcmQ="
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
https://api.example.com/users
3. API Key
# 方法1：ヘッダー
curl -H "X-API-Key: your-api-key" \
https://api.example.com/users
# 方法2：クエリパラメータ
curl "https://api.example.com/users?api_key=your-api-key"
cURLコマンド詳解
基本的なGETリクエスト
# 最もシンプルなGET
curl https://api.example.com/users
# レスポンスヘッダーを表示
curl -i https://api.example.com/users
# レスポンスヘッダーのみ表示
curl -I https://api.example.com/users
# リダイレクトをたどる
curl -L https://example.com/redirect
POSTリクエスト
# JSONデータ
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}'
# フォームデータ
curl -X POST https://api.example.com/users \
-d "name=Alice&email=alice@example.com"
# ファイルアップロード
curl -X POST https://api.example.com/upload \
-F "file=@photo.jpg" \
-F "description=My photo"
高度なオプション
# タイムアウト設定
curl --connect-timeout 5 --max-time 30 https://api.example.com
# ファイルに出力
curl -o response.json https://api.example.com/users
# サイレントモード（進捗を表示しない）
curl -s https://api.example.com/users
# 詳細出力（デバッグ用）
curl -v https://api.example.com/users
# SSL証明書の検証をスキップ（開発環境のみ）
curl -k https://self-signed.example.com
# プロキシ
curl -x http://proxy:8080 https://api.example.com
# Cookie
curl -b "session=abc123" https://api.example.com/users
# Cookieの保存と送信
curl -c cookies.txt -b cookies.txt https://api.example.com/users
よくあるHTTPステータスコード
| ステータスコード | 意味 | よくある原因 |
|---|---|---|
| 200 | OK | 成功 |
| 201 | Created | POSTによる作成成功 |
| 204 | No Content | DELETE成功 |
| 301 | Moved Permanently | 恒久的なリダイレクト |
| 304 | Not Modified | キャッシュヒット |
| 400 | Bad Request | パラメータエラー |
| 401 | Unauthorized | 未認証 |
| 403 | Forbidden | 権限不足 |
| 404 | Not Found | リソースが存在しない |
| 409 | Conflict | リソースの競合 |
| 422 | Unprocessable Entity | バリデーション失敗 |
| 429 | Too Many Requests | レート制限 |
| 500 | Internal Server Error | サーバー側エラー |
| 502 | Bad Gateway | 上流サービスが利用不可 |
| 503 | Service Unavailable | サービス過負荷 |
ToolsKuでAPIをテストする
cURLをコードに変換
- cURLからコードへの変換ツールを開く
- cURLコマンドを貼り付ける
- 対象言語（JavaScript/Python/Go/Javaなど）を選択
- 生成されたコードをコピー
例
# 入力するcURL
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token123" \
-d '{"name": "Alice"}'
JavaScriptに変換：
const response = await fetch('https://api.example.com/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer token123',
},
body: JSON.stringify({ name: 'Alice' }),
});
const data = await response.json();
APIデバッグのテクニック
1. リクエスト/レスポンスの全体を確認する
# -v で詳細情報を表示
curl -v https://api.example.com/users
# 出力：
> GET /users HTTP/1.1 ← リクエストライン
> Host: api.example.com ← リクエストヘッダー
> Authorization: Bearer ...
>
< HTTP/1.1 200 OK ← ステータスライン
< Content-Type: application/json ← レスポンスヘッダー
< X-RateLimit-Remaining: 99
<
[{"id": 1, "name": "Alice"}] ← レスポンスボディ
2. JSONレスポンスを整形する
# jq で整形
curl -s https://api.example.com/users | jq
# python を使用
curl -s https://api.example.com/users | python -m json.tool
# またはToolsKuのJSON整形ツールを使用
3. レスポンスタイムを計測する
# 詳細な時間統計
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
-o /dev/null -s https://api.example.com/users
# 出力：
# DNS: 0.012s
# Connect: 0.035s
# TTFB: 0.120s
# Total: 0.125s
4. CORS問題の切り分け
ブラウザのエラー：
Access to fetch at 'https://api.example.com' from origin 'https://app.example.com'
has been blocked by CORS policy
切り分け手順：
1. OPTIONSプリフライトリクエストを確認
curl -X OPTIONS -H "Origin: https://app.example.com" \
-H "Access-Control-Request-Method: POST" \
-i https://api.example.com/users
2. レスポンスヘッダーを確認
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400
5. 認証問題の切り分け
401 Unauthorized の切り分け：
1. トークンの有効期限が切れていないか？→ JWTデコードツールで exp を確認
2. トークンの形式は正しいか？→ Bearer プレフィックスを確認
3. トークンは送信されているか？→ curl -v でリクエストヘッダーを確認
403 Forbidden の切り分け：
1. ユーザーに権限があるか？→ ユーザーロールを確認
2. IPはホワイトリストに入っているか？→ サーバーログを確認
3. レート制限を超えていないか？→ 429ステータスコードを確認
APIテストのベストプラクティス
1. 環境変数の管理
# 機密情報は環境変数に保存
export API_BASE="https://api.example.com"
export API_TOKEN="your-token"
curl -H "Authorization: Bearer $API_TOKEN" "$API_BASE/users"
2. リクエストコレクション
#!/bin/bash
# api-test.sh
BASE="https://api.example.com"
TOKEN="Bearer $API_TOKEN"
HEADER="-H 'Content-Type: application/json' -H 'Authorization: $TOKEN'"
# ユーザー一覧を取得
get_users() { curl -s $HEADER "$BASE/users" | jq; }
# ユーザーを作成
create_user() { curl -s -X POST $HEADER -d "$1" "$BASE/users" | jq; }
# 単一ユーザーを取得
get_user() { curl -s $HEADER "$BASE/users/$1" | jq; }
# 使い方
get_users
create_user '{"name":"Bob"}'
get_user 1
3. 自動テスト
// fetch でAPIテストを書く
async function testApi() {
// GET をテスト
const listRes = await fetch('/api/users');
console.assert(listRes.status === 200, 'GET /users should return 200');
// POST をテスト
const createRes = await fetch('/api/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Test' }),
});
console.assert(createRes.status === 201, 'POST /users should return 201');
const created = await createRes.json();
console.assert(created.name === 'Test', 'Name should match');
}
よくある質問
WindowsでcURLの引用符がうまくいかない？
Windows CMDはダブルクォートを使い、PowerShellにはエスケープの問題があります：
# PowerShell の curl は Invoke-WebRequest のエイリアス
# curl.exe で本物の cURL を呼び出す
curl.exe -X POST https://api.example.com/users `
-H "Content-Type: application/json" `
-d '{\"name\": \"Alice\"}'
リクエストがタイムアウトする場合の切り分けは？
1. DNS解決が遅い？→ curl -w で time_namelookup を確認
2. 接続確立が遅い？→ curl -w で time_connect を確認
3. サーバー処理が遅い？→ curl -w で time_starttransfer - time_connect を確認
4. レスポンス転送が遅い？→ curl -w で time_total - time_starttransfer を確認
まとめ
APIデバッグは開発者の日常です。cURLコマンド、HTTPステータスコード、認証方式、デバッグテクニックを身につければ、APIの問題を素早く特定できます。ToolsKuのcURLからコードへの変換ツールとJSON整形ツールはAPIデバッグの良き相棒として、APIのテストとレスポンスの確認を素早く行えます。
#APIテスト#HTTPリクエスト#cURL#APIデバッグ#チュートリアル