| name | breaking-changes |
| description | Understand what counts as a breaking API change in api-diff-checker, and how to interpret breaking change results. Use when you need to know if a specific API change will break existing clients, understand the classification rules used by the diff engine, or explain to a reviewer why an API change is flagged as breaking. Triggers include "is this breaking", "breaking change rules", "why is this change breaking", "explain API breaking changes", "what breaks API clients", or any task involving understanding API backward compatibility. |
breaking-changes
Reference guide for how api-diff-checker classifies changes as breaking or non-breaking.
Breaking change rules
A change is classified as breaking if it can cause existing clients to fail without modification:
| Change | Why it breaks |
|---|
| Endpoint removed | Existing clients calling it will get 404 |
| Required parameter added | Existing calls without that parameter will fail with 400 |
| Parameter type narrowed (e.g. string -> integer) | Existing values may not match new type |
| Request body made required | Existing calls without a body will fail |
| Response status code removed | Clients handling that status will be confused |
| Response schema field removed | Clients reading that field will get undefined |
| Response schema field type changed | Clients parsing that type will fail |
| Security scheme added | Unauthenticated clients will get 401 |
Non-breaking changes
A change is non-breaking if existing clients continue to work unchanged:
| Change | Why it is safe |
|---|
| Endpoint added | New surface, no existing client uses it |
| Optional parameter added | Existing calls still work without it |
| Required parameter made optional | Relaxing a constraint |
| Optional response field added | Existing clients ignore unknown fields |
| Security scheme removed | Auth relaxed, existing clients still work |
Informational (no impact)
These changes do not affect behavior:
| Change | Notes |
|---|
| Description changed | Documentation only |
| Title changed | Documentation only |
| Example values changed | Not part of runtime behavior |
Checking a specific change
adc diff api-v1.yaml api-v2.yaml --only-breaking --format json | jq '.changes[]'
adc diff api-v1.yaml api-v2.yaml --format json | \
jq '[.changes[] | select(.path | contains("users"))]'
API response - checking programmatically
const result = await fetch('/api/diff', { method: 'POST', body: form });
const diff = await result.json();
if (diff.summary.breaking > 0) {
console.error('Breaking changes detected:', diff.summary.breaking);
process.exit(1);
}
Common questions
Q: Is changing a response field from required to optional breaking?
No. Clients that always check for the field will still work. Non-breaking.
Q: Is changing an enum to add a new value breaking?
Clients that use exhaustive enum matching may break. Classified as breaking.
Q: Is renaming an endpoint breaking?
Yes - the old endpoint is removed and a new one is added. The removal is breaking.
Q: Is adding a new security scheme breaking?
Yes - existing clients that do not send auth credentials will receive 401.
