Detect OpenAPI Breaking Changes Before They Break Production
A single breaking change in your API can cascade across every consumer — mobile apps, partner integrations, internal services. CodeRifts catches them automatically on every pull request, before they reach 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 `email` field from a user object.
- Enum Value Removal: Deleting an accepted value from an enumerated list, e.g., changing `status: [active, inactive, pending]` to `status: [active, inactive]`.
Type and Constraint Changes
Subtler than outright removals, these changes break clients that rely on strong typing or specific data formats. They often lead to deserialization errors or unexpected runtime exceptions.
- Changing a Field's Type: E.g., modifying a `price` field 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 `uuid` to `email`, for example.
Authentication & Authorization
Changes to security schemes are fundamental and will break all clients immediately. These are 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, often violating the assumptions built into HTTP libraries and client code.
- Changing Response Content-Type: Switching from `application/json` to `application/xml`.
- Removing a Success Status Code: No longer returning a `201 Created` on a `POST` request.
The Real-World Impact of Undetected Breaking Changes
Client Crashes & Mobile App Failures
A mobile app expecting a `user.name` field in a JSON response receives nothing. The app’s code doesn’t handle the null value and crashes on startup. Your app store ratings plummet as thousands of users are locked out.
Partner Integration Breakage
A key partner’s automated system relies on your API to sync inventory. You change an ID field from an integer to a string. Their integration fails silently, and for 12 hours, they sell products that are out of stock, leading to financial loss and a damaged relationship.
SLA Violations & Financial Penalties
Your enterprise customer has a Service Level Agreement (SLA) guaranteeing 99.9% uptime. A breaking change you deployed takes down their dashboard for 4 hours. You have now violated your SLA, triggering financial penalties and a difficult conversation with your customer.
Erosion of Developer Trust
Every unexpected breaking change erodes the trust developers have in your API. They start coding defensively, adding excessive error handling, and become hesitant to adopt new features. Your API’s adoption slows, and its reputation suffers.
How CodeRifts Detects and Categorizes Breaking Changes
CodeRifts goes beyond simple text diffs to understand the semantic meaning of your OpenAPI specification. It acts like a dedicated, tireless API expert on your team.
Automated Scanning in CI/CD
There's no manual step. By installing our GitHub App or using our CLI in your pipeline, CodeRifts scans every change to your OpenAPI files, whether they are in YAML or JSON format.
Intelligent Risk Scoring
Not all breaking changes are equal. CodeRifts analyzes multiple dimensions to assign a clear risk score (Critical, High, Medium, Low) to every change, helping your team prioritize what needs immediate attention.
- Blast Radius: Does this affect one endpoint or all of them?
- Compatibility Impact: Will this crash clients or just cause warnings?
- Security Implications: Does this change authentication or authorization rules?
- Revenue Impact: (Coming Soon) Is this endpoint tied to a high-value customer plan?
How It Works
Install the GitHub App
One click. Read-only permissions. No CI configuration needed.
Open a pull request that modifies an OpenAPI spec
CodeRifts automatically detects .yaml, .yml, and .json files that contain OpenAPI definitions.
Review the report
CodeRifts posts a detailed PR comment with every breaking change, risk score, policy violations, and a recommended semver bump.
Frequently Asked Questions
What is a breaking change in OpenAPI?
A breaking change is any modification to an API specification that can cause existing client applications to fail. This includes removing an endpoint, adding a required field to a request, changing a field’s data type, or altering authentication requirements. The goal is to avoid these surprises for your API consumers.
How do I detect breaking changes automatically?
The most reliable method is to use an automated tool like CodeRifts within your CI/CD pipeline. On every pull request or code commit, the tool can perform an OpenAPI diff between the new and old spec versions. It analyzes the changes semantically to identify and report any breaking changes before they are merged.
What's the difference between breaking and non-breaking changes?
A breaking change (e.g., removing a field) will likely cause errors for existing clients. A non-breaking, or additive, change (e.g., adding a new optional field or a new endpoint) extends the API's functionality without disrupting existing clients. Proper API versioning, often using Semantic Versioning (SemVer), dictates a major version bump (e.g., v1 to v2) for breaking changes.
Can breaking change detection run in CI/CD?
Yes, and it's highly recommended. Integrating automated detection into your Continuous Integration/Continuous Deployment (CI/CD) pipeline is the core value of tools like CodeRifts. By adding a check to your GitHub, GitLab, or Jenkins pipeline, you can block pull requests that introduce breaking changes, making your API development process safer and more predictable.
How does CodeRifts score risk?
CodeRifts scores risk by analyzing the nature and severity of a change. For example, removing an entire endpoint is "Critical" because it guarantees failure for any client using it. Changing a data type from integer to string is "High" because it will break strongly-typed clients. Adding an optional field is "Low" or "Info". This scoring helps teams focus on the most dangerous changes first.
Stop shipping breaking changes.
Install CodeRifts in 30 seconds. Free for up to 3 private repos.
See all 61+ features or compare pricing plans.