Compare API JSON fixtures without confusing formatting with behavior

Capture a reproducible pair of responses

Use the same endpoint, request parameters and development data before and after a change. Record the relevant HTTP status and response headers separately, because a JSON-only diff cannot compare them. Remove production credentials and customer records. Prefer a small fixture that preserves the failing behavior over a large capture that hides important differences among thousands of changing values.

Separate representation from semantic changes

Indentation and object key order can change without changing the parsed object. A structural diff ignores those presentation differences. It still distinguishes a string from a number, a missing field from null and one array order from another. Those distinctions can break clients even when the payload looks superficially similar.

Before: {"id": 7, "enabled": false}
After:  {"enabled": false, "id": 7}
Result: equal

After:  {"enabled": false, "id": "7"}
Result: changed at /id

Normalize only fields whose changes you intend to ignore

A generated request id or timestamp can make every fixture different. Remove those fields in a named, explicit normalization step if they are irrelevant to the assertion. Do not remove every field ending in id or time; that can hide a real regression. Document why each ignored path is safe and test the excluded behavior separately when it matters.

Array indexes are not entity identifiers

The diff checker compares array positions. If an API returns the same users in a new order, changes at /users/0 and /users/1 may reflect reordering rather than edited users. If the contract does not promise order, sort copies of the records by a stable unique id before comparing. If order is part of the contract, leave it intact. Never sort in a way that removes duplicates or masks missing records.

Turn an observed difference into a contract test

A snapshot shows what changed; it does not decide whether the change is correct. Assert the intended status code, required fields, field types, important values and error cases. Review additions as well as removals: accidentally returning a private field is a regression even if every old field is still present. Use string representations for large identifiers beyond JavaScript’s safe integer range, and verify the same fixture in your application runtime.