Detect OpenAPI breaking changes before they break production
Why breaking changes are dangerous#
API contracts are implicit promises. When you break them, you break trust — and usually someone else's production deployment.
- Mobile apps — Users can't update instantly. A breaking change means crashes for everyone on the old version, and you can't force an App Store update.
- Partner integrations — Partners build on your API. A removed field or changed type breaks their integration, and they find out in production, not in a PR review.
- Microservices — Internal services depend on each other's contracts. One team's "minor change" becomes another team's midnight incident.
A taxonomy of breaking changes#
Structural removals#
The most obvious and severe category. When consumers try to access something that no longer exists, they will almost certainly crash. CodeRifts flags these as critical issues.
- Endpoint removal — deleting a path-method combination, like
DELETE /api/v1/users/{id}. - Response field removal — removing a field from a response body, like the
emailfield from a user object. - Enum value removal — deleting an accepted value from an enumerated list, e.g.
status: [active, inactive, pending]→status: [active, inactive].
Type and constraint changes#
Subtler than outright removals, these changes break clients that rely on strong typing or specific data formats.
- Changing a field's type — e.g. modifying a
pricefield from an integer to a string. - Adding a required field — making a previously optional field in a request body mandatory.
- Changing format constraints — altering a string format from
uuidtoemail, for example.
Authentication & authorization#
Changes to security schemes are fundamental and will break all clients immediately — among the highest-risk changes possible.
- Changing the security scheme — switching from OAuth2 to ApiKey authentication.
- Adding a new scope — requiring a new permission scope for an existing endpoint.
Response format & behavior#
These changes alter the fundamental way a client interacts with an endpoint.
- Changing response content-type — switching from
application/jsontoapplication/xml. - Removing a success status code — no longer returning a
201 Createdon aPOSTrequest.
The real-world impact of undetected breaking changes#
- Client crashes & mobile app failures — A mobile app expecting a
user.namefield in a JSON response receives nothing. The app's code doesn't handle the null value and crashes on startup. - Partner integration breakage — A key partner's automated system relies on your API to sync inventory. You change an ID field from integer to string. Their integration fails silently, and for 12 hours they sell products that are out of stock.
- SLA violations & financial penalties — Your enterprise customer has an SLA guaranteeing 99.9% uptime. A breaking change takes down their dashboard for 4 hours. You have now violated your SLA.
- Erosion of developer trust — Every unexpected breaking change erodes the trust developers have in your API. They start coding defensively and become hesitant to adopt new features.
How CodeRifts detects and categorizes breaking changes#
- Automated scanning in CI/CD — No manual step. Install the GitHub App or use the CLI — CodeRifts scans every change to your OpenAPI files, YAML or JSON.
- Intelligent risk scoring — Not all breaking changes are equal. CodeRifts analyzes blast radius, compatibility impact, security implications, and economic impact (a configurable heuristic cost estimate: engineer rate × migration hours) and assigns a clear risk score.
Verified finding#
Every breaking-change verdict ships with a signed, independently verifiable receipt. On the public demo pull request coderifts/demo#4 (2026-07-21), CodeRifts issued a deterministic BLOCK on 3 breaking changes and signed the verdict as an Ed25519 receipt.
- Verdict fingerprint:
sha256:70699341…cfec - Change IR hash:
sha256:f3de7721…a334 - Receipt key / issued:
2026-07-k1· 2026-07-21
The receipt is in the PR comment. Verify it yourself, offline — see Portable Verification.