api-response-diff
v0.1.0
Published
Compare JSON API response bodies; classify breaking vs non-breaking changes for contract tests, CI gates, and semver-style checks
Maintainers
Readme
api-response-diff
Compare two JSON API response bodies and split changes into breaking vs non-breaking—handy for contract tests, release checks, and OpenAPI-adjacent guardrails. Uses json-diff-core under the hood.
const { compareApiResponses } = require('api-response-diff');
const result = compareApiResponses(
{ data: { id: 1, email: '[email protected]' } },
{ data: { id: 1 } }
);
console.log(result.summary); // e.g. "1 breaking, 0 non-breaking"
console.log(result.hasBreakingChanges); // true
console.log(result.breaking[0].path); // "data.email"Install
npm install api-response-diffDefault rules (severity)
Breaking (typical):
- Removed fields or array elements
- Type narrowing (e.g. string → number where it breaks consumers)
- Shorter arrays when items disappear
Non-breaking (typical):
- New optional fields
- Same-type value updates
- Widening (e.g.
null→ concrete value)
Exact heuristics live in the classifier; override per path when your API contract differs.
API
compareApiResponses(before, after, options?)
Returns ApiResponseDiffResult:
| Field | Description |
| --- | --- |
| breaking / nonBreaking / unknown | Classified changes |
| all | Full list with severity and reason |
| hasBreakingChanges | Quick gate for CI |
| summary | Short counts string |
Options
compareApiResponses(v1, v2, {
ignorePaths: ['meta.generatedAt'],
breakingPaths: ['data.status'], // force value edits here to count as breaking
nonBreakingPaths: ['data.banner'],
});CI gate example
const { hasBreakingChanges, summary } = compareApiResponses(snapshot, live);
if (hasBreakingChanges) {
process.exitCode = 1;
console.error('API breaking changes:', summary);
}Related packages
- json-diff-explainer — plain-English lines for any JSON pair
- json-diff-core — low-level
diffJsonwhen you own classification
Why teams pick this
vs eyeballing JSON: breaking vs non-breaking rules for API contract CI gates.
Search terms: api diff, breaking change, json api, contract testing, semver, response compare, backward compatibility, integration test, typescript, node
