学ぶ / チートシート
API テストのための HTTP チートシート
テスターに必要な HTTP の知識を 1 枚にまとめました。どのメソッドが安全で冪等か、状況ごとにどのステータスコードを返すべきか、アサートする価値のあるヘッダー、日常的に使う cURL のフラグ、そしてレスポンスごとのチェックリストです。
HTTP セマンティクスは RFC 9110、Problem Details は RFC 9457 に準拠 で確認済み
メソッド
| メソッド | 用途 | 安全 | 冪等 |
|---|---|---|---|
GET | リソースやコレクションを読み取る | はい | はい |
HEAD | GET と同様だがヘッダーのみ | はい | はい |
OPTIONS | 許可されたメソッド、CORS プリフライト | はい | はい |
POST | 作成する、またはアクションを実行する | いいえ | いいえ |
PUT | リソース全体を置き換える | いいえ | はい |
PATCH | 一部のフィールドを変更する | いいえ | 保証されない |
DELETE | リソースを削除する | いいえ | はい |
冪等とは、リクエストを繰り返してもサーバーの状態が同じになることです。レスポンスは異なる場合があり、2 回目の DELETE は 404 を返すことがあります。
アサートすべきステータスコード
| コード | 意味 | 典型的なテスト |
|---|---|---|
200 OK | ボディ付きの成功 | 既存のリソースを GET する |
201 Created | リソースが作成された | 有効なデータを POST し、Location ヘッダーを確認する |
204 No Content | 成功、ボディは空 | DELETE、または何も返さない PUT |
301 / 308 | 恒久的に移動した | 古い URL がリダイレクトされる。308 はメソッドを維持する |
304 Not Modified | キャッシュがまだ有効 | If-None-Match: <etag> 付きの GET |
400 Bad Request | リクエストの形式が不正 | 不正な JSON、誤った型 |
401 Unauthorized | 認証されていない | トークンがない、または期限切れ |
403 Forbidden | 認証済みだが許可されていない | 別のユーザーのリソースにアクセスする |
404 Not Found | リソースが存在しない | 未知の id（または見せられないリソースを隠す場合） |
405 Method Not Allowed | この URL では使えないメソッド | 読み取り専用エンドポイントへの DELETE |
409 Conflict | 現在の状態と衝突する | メールアドレスの重複、古いバージョン |
415 Unsupported Media Type | ボディの形式を受け付けない | JSON エンドポイントに text/plain を送る |
422 Unprocessable Content | JSON としては正しいが値が無効 | ビジネスルールのバリデーションエラー |
429 Too Many Requests | レート制限された | リクエストを集中させ、Retry-After を確認する |
500 Internal Server Error | サーバーのバグ | 想定されることはない。常に欠陥 |
502 / 503 / 504 | 上流の障害、利用不可、タイムアウト | 依存先のダウン。リトライを確認する |
確認すべきヘッダー
| ヘッダー | 例 | 理由 |
|---|---|---|
Content-Type | application/json; charset=utf-8 | レスポンスの形式がボディと一致している |
Accept | application/json | クライアントが形式を要求する。未対応なら 406 を期待 |
Authorization | Bearer eyJhbGciOi… | トークン認証。ない場合は 401 |
Location | /api/orders/1043 | 201 Created とリダイレクトで設定される |
Cache-Control | no-store | 個人情報や機密データはキャッシュしてはいけない |
ETag / If-None-Match | "a1b2c3" | 条件付き GET → 304 |
Retry-After | 30 | 429 や 503 と一緒に送られる |
Set-Cookie | sid=…; HttpOnly; Secure; SameSite=Lax | セッション Cookie には HttpOnly と Secure が必要 |
Access-Control-Allow-Origin | https://app.example.com | CORS：認証情報付きのリクエストでは * を使わない |
cURL
| やりたいこと | コード |
|---|---|
| ステータスとヘッダーを表示 | curl -i https://api.example.com/users/1 |
| リクエスト・レスポンスの完全なトレース | curl -v https://api.example.com/users/1 |
| JSON を POST | curl -X POST https://api.example.com/users \
-H 'Content-Type: application/json' \
-d '{"email":"qa@example.com"}' |
| Bearer トークン | curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me |
| Basic 認証 | curl -u user:pass https://api.example.com/admin |
| リダイレクトをたどる | curl -L https://example.com/old |
| ステータスコードだけ | curl -s -o /dev/null -w '%{http_code}' https://api.example.com/health |
| スクリプトで 4xx/5xx を失敗扱いにする | curl --fail-with-body https://api.example.com/health |
Windows の cmd では、シングルクォートをダブルクォートに置き換え、内側のダブルクォートをエスケープします。
すべてのレスポンスで確認すること
| チェック | 例 |
|---|---|
| ステータスコード | 「何らかの 2xx」ではなく正確に 201 |
| ボディのスキーマ | 必須フィールドがあり、型が正しく、余計な機密フィールドがない |
| 値 | 入力がそのまま返っている。計算されるフィールド（合計、日付）が正しい |
| ヘッダー | Content-Type、Location、Cache-Control |
| エラーの形式 | 一貫したエラー形式（例：RFC 9457 の Problem Details）で、役立つメッセージがある |
| 副作用 | GET し直すと、レコードが存在する（または存在しない） |
| レスポンスタイム | 合意した予算内に収まっている |