How to compare two JSON API responses

Updated: June 2026 · All guides

API upgrades, cache invalidation bugs, and environment drift all show up as JSON that looks similar but behaves differently. Comparing two responses side by side — staging vs production, v1 vs v2, before vs after a deploy — is one of the fastest ways to pinpoint what changed. This guide walks through a repeatable workflow using local, in-browser tools so credentials and customer data never leave your machine.

When diffing helps

• A mobile client breaks after a backend release — you need to see which fields disappeared
• Staging returns 200 but production returns different shapes for the same endpoint
• You merge two microservice responses and want to verify the combined object
• Documentation says the schema changed; you want proof against real samples

Step 1: Capture both payloads

Export JSON from your API client (Postman, Insomnia, curl, browser DevTools Network tab). Save as .json files or copy to clipboard. Label them clearly — e.g. A = production, B = staging — so you do not invert the comparison.

If responses are large, consider trimming to the subtree you care about (e.g. only data.items) before diffing. Smaller documents make human review faster.

Step 2: Normalize formatting

Whitespace and key order create noise. In JSON Diff, use Format A and Format B to pretty-print both sides with consistent indentation. Then use Sort A and Sort B to alphabetically order object keys at every level.

Step 3: Read the diff

Monaco’s diff engine highlights additions (green), deletions (red), and modifications. Press F7 to jump between changes. Focus on:

• Removed keys — often breaking for clients that assume presence
• Type changes — string → number, null → object
• Array length changes — pagination or filtering differences
• Nested path changes — renamed fields deep in metadata

Example: subtle breaking change

Version A (production):

{
  "user": {
    "id": 100,
    "profile": { "displayName": "Sam" }
  }
}

Version B (staging) after refactor:

{
  "user": {
    "id": "100",
    "profile": { "name": "Sam" }
  }
}

After sorting keys, you see two real changes: id became a string (breaks strict clients) and displayName was renamed to name. A line-based diff without sorting might bury these among formatting artifacts.

Step 4: Validate against schema (optional)

If you have a JSON Schema, paste each response into JSON Editor Pro and run validation. A response can diff-clean against an older sample yet fail schema — e.g. a new required field your mobile app does not send yet. See our JSON Schema validation guide.

Comparing YAML configs

Many APIs expose YAML configs (Kubernetes, CI files). Use YAML Diff with the same sort-and-format workflow. YAML adds indentation sensitivity — format both sides before comparing.

Security note

API responses often contain emails, tokens, or internal IDs. Avoid pasting them into cloud-based diff tools. Browser-local diffing (as on webtoolkit.in) keeps payloads on your device. Clear editor content when finished on shared machines, or use private browsing.

Checklist before closing a ticket

1. Both sides formatted and key-sorted
2. Every diff hunk classified: breaking / safe / intentional
3. Schema validation run on both samples (if schema exists)
4. Changelog or OpenAPI spec updated to match reality

Capturing responses with curl

From a terminal, save responses for side-by-side comparison:

curl -s -H "Authorization: Bearer TOKEN" \
  https://api.example.com/v1/users/42 \
  -o prod-user.json

curl -s -H "Authorization: Bearer TOKEN" \
  https://staging-api.example.com/v1/users/42 \
  -o staging-user.json

Import both files into JSON Diff (Import A / Import B), then format and sort. Redact tokens before saving files on shared drives.

Noise you can usually ignore

Not every diff is a breaking change. Learn to filter:

• Timestamps — updatedAt, generatedAt change every request
• Request IDs — tracing UUIDs differ per call; compare structure, not values
• Pagination cursors — nextPageToken changes; focus on items array shape
• Floating-point formatting — 1.0 vs 1 may highlight; check semantic equality

For timestamp-heavy APIs, copy only the subtree you care about into both panes before diffing — e.g. strip top-level meta if you only need data.

Classifying changes for your team

When reviewing diffs, label each change so release notes stay accurate:

• Breaking — removed field, type change, renamed key, stricter null handling
• Safe additive — new optional field; old clients ignore it
• Behavioral — same JSON shape, different values (sort order, default pagination size)
• Documentation-only — spec was wrong; API unchanged; update OpenAPI not code

Array and list diffs

JSON arrays are ordered. Reordering permissions: ["read", "write"] vs ["write", "read"] shows as a change even when sets are equal. If order does not matter, sort array contents (manually or in a script) before diffing, or compare sorted stringified versions of each element.

For paginated lists, diff page 1 from staging and production separately — comparing full aggregated exports when page sizes differ creates misleading length changes.

FAQ

Diff says everything changed but the API “looks the same”

Run Sort A and Sort B. If still noisy, check for whitespace-only or key-order differences. Pretty-print both sides with the same indent (2 vs 4 spaces creates false diffs).

Should I diff raw HTTP response or parsed JSON?

Always parse first. Diffing raw bytes includes header order and encoding artifacts. Paste body JSON only.

Can I diff XML API responses?

Yes — use XML Diff with the same normalize-then-compare mindset. SOAP and legacy enterprise APIs benefit especially from local diffing when responses contain account data.