Is my API change backwards compatible?

01 / WHAT IT MEANS

Backward compatibility and the client contract.

A change is backwards compatible when every existing client can continue using the API without modification. The moment a deployed client breaks because of a server-side spec change, compatibility is lost — and your consumers notice before you do.

Backward compatibility is not about what you intended. It is about what the specification actually allows. Removing an endpoint a client depends on, or turning an optional parameter into a required one — each produces the same result: a client that worked yesterday does not work today. The OpenAPI specification defines the contract; any change that narrows, removes, or reinterprets an existing clause breaks that contract.

Knowing which changes are safe and which are not saves you from emergency rollbacks, late-night reverts, and unhappy integrators.

02 / SAFE CHANGES

Changes that ARE backwards compatible.

These additions extend the API surface without invalidating anything an existing client depends on:

Adding new endpoints. A new path or method does not affect any existing call. Old clients never use it. This is the safest category of change.

Adding optional parameters. A new query parameter, header, or request body field that defaults to the old behaviour is additive. Clients that omit it see the same response as before.

Adding response fields. As long as clients are loosely coupled — they ignore unrecognised fields — a new property is invisible to existing consumers. This is safe in practice.

Adding new response status codes. Introducing a new success or redirect code does not break clients that already handle the existing codes.

Adding new request headers. A header that is optional and ignored by old clients is additive. The server must continue to handle requests that omit it.

03 / BREAKING CHANGES

Changes that are NOT backwards compatible.

These changes remove, narrow, or reclassify something a client depends on. Deploying them without a version bump or migration window will break consumers:

Removing endpoints. The most obvious breaking change. Any client that calls a removed path receives a 404 or equivalent error. This also includes removing an HTTP method from an existing path.

Removing fields. Deleting a property from a response body or making it nullable where it was previously guaranteed causes parsing failures or null-pointer errors on the client side.

Making optional fields required. Adding required: true to a previously optional request body property invalidates every existing request that omits it. This is one of the most common accidental breaking changes in OpenAPI diffs.

Narrowing types. Changing a field from string to integer, reducing an enum set, or tightening a pattern constraint breaks clients that send or receive values outside the narrowed range.

Changing existing response codes. Reassigning a 200 response to a different schema, or replacing a 200 with a 201 for the same endpoint, forces clients to update their response handlers.

Removing response headers. Deleting a documented response header — such as X-RateLimit-Remaining — breaks clients that depend on reading that header after a call.

04 / HOW TO CHECK

How to check before you deploy.

The fastest way to verify backward compatibility is to diff the old specification against the new one using a structural comparison tool. A text diff shows what lines changed, but it cannot tell you whether any of those changes break a client.

Upload both OpenAPI specs — yesterday's and today's, or main and your feature branch — and look at the BREAKING bucket. Every item in that bucket is a change an existing client cannot survive without modification. Ask three questions: Is this endpoint or field depended on in production? Can I communicate the change before shipping? Do I need a new version instead?

The ADDITIVE bucket is green — those changes are safe. The COSMETIC bucket is informational. The BREAKING bucket is your decision point.