API Compatibility

Every contract change reaches consumers the project does not deploy. Classifying each one decides whether consumers need a new version, a review, or nothing at all. An unclassified change ships the decision to consumers as a surprise.

Reviewed forWhich independent-consumer contract changes lack a classification? Look at the change reviews.

Marked guidance: a reviewer answers this question.

A consumer can depend on any element of the contract: a field it reads, a status it branches on, an authentication scheme it implements. Removing, renaming, narrowing, or retyping any of them breaks the consumer that depended on it. Calling each such change breaking routes it to versioning instead of silent release.

Reviewed forWhich removed, renamed, narrowed, retyped, or authentication changes lack a breaking verdict? Look at the change reviews.

Marked guidance: a reviewer answers this question.

Consumers read query output fields, branch on refusal codes, and parse integration-event payloads, so a removed field breaks every consumer that relied on it while the route stays green. Calling each such removal breaking routes it to versioning and notice instead of silent release.

Reviewed forWhich removed output fields, refusal codes, or integration-event payload fields lack a breaking verdict? Look at the change reviews.

Marked guidance: a reviewer answers this question.

An optional field, endpoint, or query parameter asks nothing of existing callers: they send and interpret the same values as before. Classifying these as compatible keeps routine growth cheap. Treating them as breaking would version the API for changes nobody has to adopt.

Reviewed forWhich optional additions lack a record of why existing behavior stays? Look at the change reviews.

Marked guidance: a reviewer answers this question.

Generated clients often switch exhaustively over enum values and discriminator cases. A new value that the server now sends reaches a client with no branch for it, which rejects a valid response. Consumer review checks that each client handles the new case before it ships.

Reviewed forWhich added enum values or discriminator cases shipped without consumer review? Look at the consumer reviews.

Marked guidance: a reviewer answers this question.

Consumers branch on stable Problem Details codes the way they branch on statuses. Removing or reassigning a code breaks that branch while the status stays green. Treating the code as breaking keeps error handling stable across versions.

Reviewed forWhich removed or reassigned stable codes lack a breaking verdict? Look at the change reviews.

Marked guidance: a reviewer answers this question.

A structural diff cannot prove every change compatible: some changes need a person to judge their effect on consumers. Classifying the unclear ones as breaking routes them to consumer review instead of release. The cost of a needless review is smaller than the cost of a broken consumer.

Reviewed forWhich unclear changes shipped as compatible without consumer review? Look at the change reviews.

Marked guidance: a reviewer answers this question.

A breaking change past production breaks promises consumers release against, so the decision states the impact: which consumers break, what they must change, and when the old shape leaves. A developer review alone cannot accept breaking what the product promised.

Reviewed forWhich breaking Behavior changes past production lack a decision naming their consumer impact? Look at the decisions.

Marked guidance: a reviewer answers this question.

Each release stores its OpenAPI document as an immutable baseline. Later changes diff against it instead of against memory or a mutable file. Without a retained baseline, the project cannot prove what changed between two releases.

Reviewed forWhich releases lack a retained OpenAPI baseline? Look at the release artifacts.

Marked guidance: a reviewer answers this question.

The diff against the supported baseline runs both locally and in continuous integration. The local run catches a breaking change while it is cheap to rework. The CI run catches it when the local run was skipped.

Reviewed forWhich changes skipped the local or continuous integration diff against the baseline? Look at the local runs and the CI runs.

Marked guidance: a reviewer answers this question.

A breaking diff that fails CI stops until a new API version or a recorded consumer decision authorizes it. The failure forces the compatibility decision before release, while versioning is still possible. A warning nobody has to answer authorizes nothing.

Reviewed forWhich breaking diffs passed without a new version or a recorded decision? Look at the CI runs.

Marked guidance: a reviewer answers this question.

Generated clients turn each operationId into a method name, and tools use it to reference the operation. A deliberate identifier keeps those names stable and meaningful. An endpoint whose shape an outside specification fixes is exempt, because the project does not own that contract.

An OAuth redirect endpoint, an OIDC discovery document, a provider webhook receiver, and a well-known resource each carry a shape the other party defines.

Reviewed forWhich independent-consumer operations lack a deliberate operationId? Look at the OpenAPI document.

Marked guidance: a reviewer answers this question.

A compatible change promises existing consumers keep working. Renaming the operationId breaks that promise for every generated client and every stored operation reference. The identifier stays until a new version takes over.

Reviewed forWhich compatible changes renamed the operationId? Look at the OpenAPI diff.

Marked guidance: a reviewer answers this question.

The new version needs its own contract names so the retained version keeps its own. A new operationId for each changed operation separates the two. Sharing one identifier across versions would let the new contract rename the old one.

Reviewed forWhich new versions reuse the operation ID of a changed contract? Look at the versioned OpenAPI documents.

Marked guidance: a reviewer answers this question.

Breaking changes need a boundary: a new route or a documented media-type version. Both contracts then serve at once, and each consumer moves on its own schedule. Without the boundary, one contract serves two incompatible expectations.

Reviewed forWhich breaking contracts ship without a new route or media-type version? Look at the versioned API surface.

Marked guidance: a reviewer answers this question.

A consumer the project does not deploy moves on its own release cadence. The declared support window states how long the previous version stays available for that move. Removing it early strands consumers that kept to the published plan.

Reviewed forWhich previous versions left before their support window? Look at the deployed versions beside the declared window.

Marked guidance: a reviewer answers this question.

A removal touches consumers the project does not control, so the decision names each affected consumer, the deadline, and the removal condition. Recording happens before any removal, while the plan can still change. An unrecorded retirement removes first and notifies whoever complains.

Reviewed forWhich retirements lack affected consumers, a deadline, a removal condition, or recording before removal? Look at the versioning decisions.

Marked guidance: a reviewer answers this question.

Consumers discover a planned removal only when the API tells them. A documented deprecation signal, such as Deprecation and Sunset headers, announces the removal on the operation itself. A removal with no signal arrives as an outage to every consumer that missed the release notes.

Reviewed forWhich operations scheduled for removal lack a deprecation signal? Look at the public operations.

Marked guidance: a reviewer answers this question.

Headers announce the removal on the operation, but consumers plan from release notes. The consumer CHANGELOG.md names each operation scheduled for removal in the one place consumers already read. A deprecation missing from the changelog reaches only the consumers that inspect headers.

Reviewed forWhich operations scheduled for removal are missing from the consumer changelog? Look at the consumer CHANGELOG.md.

Marked guidance: a reviewer answers this question.

A deprecation decision records the sunset date and the replacement operation, so each consumer knows when to move and where to go. Nothing is removed before the decision is recorded. A removal without a recorded replacement strands the consumer that depended on the old operation.

Reviewed forWhich deprecations lack a sunset date, a replacement, or recording before removal? Look at the deprecation decisions.

Marked guidance: a reviewer answers this question.

Error handling is consumer code: it branches on Problem Details type, code, field-error codes, and documented statuses. Versioning those elements with the contract keeps error handling working across releases. An error shape that changes outside versioning breaks the consumer's failure path, which is the path least tested.

Reviewed forWhich type, code, field-code, or status changes shipped outside versioning? Look at the versioned error surface.

Marked guidance: a reviewer answers this question.

A new error outcome reaches consumers written before it existed. Adding it only when existing consumers handle an unknown code safely keeps old clients working against the new contract. An outcome old clients cannot parse turns their error path into a crash.

Reviewed forWhich added error outcomes break existing consumers on unknown codes? Look at the consumer error handling.

Marked guidance: a reviewer answers this question.

A structural diff compares documents; it never compiles a client. Testing each first-party generated client against the changed document compiles it and exercises its changed operations. The client's compiler and its exhaustive switches catch the breaks the diff cannot see.

Reviewed forWhich first-party clients skip compiling or exercising the changed contract? Look at the client test runs.

Marked guidance: a reviewer answers this question.

A consumer outside the product reads the fact without reading the product's code, so the integration-event record states what the consumer may rely on: the direction, the payload with its classifications, and the trust readers place in it. litespec/core/edges#describe-every-integration-event-for-its-direction states the record. An undeclared fact reaches outside consumers as an implementation detail that changes without notice.

Reviewed forWhich outside-consumed facts lack an integration-event record with direction, payload, and trust? Look at the integration-event records beside the outside consumers.

Marked guidance: a reviewer answers this question.

An integration event is a contract with consumers the project does not deploy, so its changes need the same verdicts as HTTP contract changes. Reusing the contract classification keeps one meaning of breaking, compatible, and needs-review across both surfaces. A separate event verdict would let one change read as compatible for events and breaking for HTTP.

Reviewed forWhich integration-event changes lack a breaking, compatible, or needs-review verdict? Look at the event reviews.

Marked guidance: a reviewer answers this question.

Outside consumers move on their own release cadence, so the breaking change ships beside the retained version instead of replacing it. Each consumer moves to the new version on its own schedule. Without the retained version, one event serves two incompatible expectations.

Reviewed forWhich breaking event changes ship without a new version beside the retained one? Look at the integration event versions.

Marked guidance: a reviewer answers this question.

A retired version strands every consumer still reading it, so the declared support window states how long the version stays available and the notice tells consumers when to move. Retiring early or silently turns a planned removal into an outage for the consumers that kept to the published plan.

Reviewed forWhich retired event versions left before their support window or without notice? Look at the retirement records beside the event consumers.

Marked guidance: a reviewer answers this question.