APIレスポンスボディの比較によるエンドポイント変更のデバッグ

APIレスポンスのDiff

APIレスポンスの比較は重要なデバッグおよびテスト手法です。同じエンドポイントからのレスポンスボディを異なるバージョン、環境、時間帯でDiffすることで、何が変更されたか、その変更が破壊的かどうかを素早く特定できます。

一般的なシナリオ

1. バージョン比較： /api/v1/users vs. /api/v2/users
2. 環境比較： ステージング vs. 本番のレスポンス
3. リグレッション検出： 今日のレスポンス vs. 昨日のベースライン
4. マイグレーション検証： データベースマイグレーション前後

JSONレスポンスの比較

// v1レスポンス
{
  "user": {
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "created": "2024-01-15T10:30:00Z"
  }
}

// v2レスポンス
{
  "user": {
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "role": "admin"
  }
}

検出された変更

名前変更: user.created → user.createdAt
変更:    タイムスタンプ形式にミリ秒が追加
追加:    user.role: "admin"

破壊的変更と非破壊的変更

変更	破壊的？	理由
フィールド追加	通常いいえ	クライアントは未知のフィールドを無視すべき
フィールド削除	はい	依存するクライアントが壊れる
フィールド名変更	はい	旧フィールド名が使えなくなる
型変更	はい	"id": 123 → "id": "123"
null導入	場合による	クライアントがnullを処理しない場合
形式変更	場合による	クライアントの解析方法に依存

APIのDiff戦略

• 動的フィールドを無視 — タイムスタンプ、リクエストID、セッショントークン
• Diff前の正規化 — キーのソート、一貫したフォーマット
• 型を考慮した比較 — "5" vs 5を型変更としてフラグ
• 配列順序の処理 — 比較前にIDで配列をソート

CI/CDでのAPI Diffの自動化

# ベースラインを取得
curl -s https://api.example.com/v1/users > baseline.json

# 現在のバージョンを取得
curl -s https://api.example.com/v2/users > current.json

# Diff
diff <(jq -S . baseline.json) <(jq -S . current.json)

テストスイートでAPIレスポンス比較を自動化するためにスナップショットテストフレームワークを使用してください。