Comparing API Response Versions with JSON Diff

When an API evolves from v1 to v2, the response structure often changes significantly. A JSON diff between sample responses from both versions reveals exactly what changed, helping API consumers prepare for the migration and helping API developers document breaking changes.

Example API version comparison:

// v1 Response
{
  "user_id": 42,
  "user_name": "alice",
  "email_address": "alice@example.com",
  "created": "2024-01-15",
  "is_active": 1
}

// v2 Response
{
  "id": 42,
  "username": "alice",
  "email": "alice@example.com",
  "createdAt": "2024-01-15T00:00:00Z",
  "isActive": true,
  "roles": ["user"]
}

The diff reveals multiple categories of changes:

Renamed fields:

• user_id -> id
• user_name -> username
• email_address -> email
• created -> createdAt
• is_active -> isActive

A basic diff tool reports these as removals + additions. Field rename detection requires heuristic matching (same value, similar key name) that some advanced diff tools provide.

Type changes:

• is_active: number 1 -> boolean true
• created: date string -> ISO 8601 datetime string

New fields:

• roles: an entirely new array field

Naming convention changes:

• snake_case -> camelCase throughout

How to systematically compare API versions:

1. Capture sample responses from both versions for the same resource.
2. Run a JSON diff to get the full list of changes.
3. Categorize changes: additions (safe), removals (breaking), renames (breaking), type changes (breaking).
4. Document each breaking change in the API migration guide.
5. Provide a compatibility layer or deprecation period for removed/renamed fields.

Automating version comparison:

Integrate JSON diff into your CI/CD pipeline. Store sample responses as fixtures and run diffs on every release to detect unintended changes. Tools like JSON Schema validation can complement diffs by catching structural violations.