09 / Change without surprise

Catch breaking API changes before clients discover them

Validate OpenAPI contracts, compare revisions, classify meaningful changes, and connect contract findings to tests and release decisions.

contract://v1 → v21 breaking

+GET /invoices/{id}safe

−customer.emailbreaking

~status: string → enumreview

recommended release MAJOR

Working reference

What goes in, what comes out, and what the result can prove.

INPUTOpenAPI documents or two contract versions

OUTPUTValidation findings and classified compatibility changes

Concrete artifact

REMOVED  GET /v1/orders/{id}        breaking
CHANGED  status enum + CANCELLED     compatible addition
CHANGED  customer.email now required breaking

Review sequence

Parse both documents before comparing paths and schemas.

Separate breaking, risky and compatible changes.

Name the operation, field and client behavior affected.

Limits

A schema-compatible change can still break undocumented client assumptions.
Runtime behavior and data quality require tests in addition to contract comparison.
Generated specifications must be reviewed against the deployed API.

Questions worth answering

What formats are supported?

OpenAPI is the primary contract format, with related conversion and schema workflows available.

What counts as a breaking change?

Examples include removing operations or fields, narrowing accepted values, and changing required inputs in ways existing clients cannot satisfy.

Can this run in CI?

Yes. Contract checks can be integrated into delivery workflows through API or exported tooling.

Next move

Keep the first step small. Move into a workspace when the result deserves to be saved, repeated, or shared.