OpenAPI change review process

An API can return 200 OK and still break every client that depends on its contract. Uptime monitoring answers whether an endpoint responds. This guide covers the judgement around an OpenAPI diff: where the baseline comes from, how to reason about direction, what should fail automatically, and what still drifts after merge.

Start from a reproducible baseline

Compare the proposed specification with the exact OpenAPI artifact shipped by the base revision. A mutable documentation URL is a poor pull-request baseline because it may change between two reviews of the same commit. Store or generate both versions so the identical pair can be reproduced locally when someone disputes the report.

Validate both documents before diffing them. A malformed or partially generated spec produces a misleading compatibility report, and reviewers stop trusting the gate after the first false alarm. The CI workflow guide covers the mechanics of running this in a pipeline; this page covers the decisions around it.

Reason about direction, not diff lines

For requests, widening what the server accepts is safer than narrowing it. For responses the perspective reverses: the server producing a new shape may exceed what an old client tolerates. Removing a response property is breaking because consumers may read it. A property that was always present but becomes optional is risky in the same way, because clients dereference it without an absence check.

Enum edits are directional too. Removing a value from a request enum rejects calls that used to be valid. Adding a value to a response enum can break a consumer that compiled an exhaustive switch with no fallback branch. A diff that assigns one severity to every enum edit will be both too loud and too quiet.

Separate what fails from what needs review

Not every flagged change deserves the same response. Removing an operation should fail the build. Tightening numeric bounds, changing a string format, editing a default value, or dropping an optional request parameter can change behaviour while the JSON type stays identical; those need a human, not a red build. Documentation-only edits should remain visible without paging the same people as a deleted endpoint.

Four buckets — breaking, potentially breaking, additive, and documentation — keep alerts actionable. The classification rules describe where each kind of change belongs.

A worked example

Suppose GET /v1/users/{id} previously returned an object with id and email. The proposed contract removes email, adds a required expand query parameter, and adds an optional displayName response field. The useful classification is:

• removed email: breaking, because consumers may read it;
• required expand: breaking, because existing callers do not send it;
• added optional displayName: non-breaking for clients that ignore unknown fields.

That report tells a reviewer exactly what existing clients must change. A raw line diff of generated YAML does not.

Monitor drift after merge

Pull-request checks cover planned source changes. They do not catch a gateway configuration edit, a generated artifact published from another repository, or a manual production change. Scheduled monitoring compares the deployed or published contract with the last known baseline and records when the difference first appeared, which is the question an incident review actually asks.

Monitoring complements integration tests rather than replacing them. The OpenAPI document can be stable while runtime behaviour changes, and a server can ship a breaking behaviour without ever touching its specification. API Guard performs this scheduled comparison and reports severity before a changed contract reaches consumers.

Frequently Asked Questions

Related Tools and Guides