Breaking API changes are one of the easiest ways to accidentally disrupt production systems.
They often slip through code review because the service itself still works — but client integrations fail immediately after deployment.
A Common Example
Consider a small change in an OpenAPI specification:
age: integer → age: string
From the service's perspective, everything still works.
But any client expecting an integer now receives a string, which can break applications consuming the API.
These types of issues are easy to miss during pull request reviews, especially when OpenAPI specs grow large.
Types of Breaking Changes
Some examples of changes that can break API consumers include:
- Removing an endpoint
- Deleting a required field
- Changing a field type
- Removing an enum value
- Making an optional parameter required
Even small modifications can break downstream systems that depend on the API contract.
Detecting Breaking Changes in CI
One approach to preventing these issues is comparing OpenAPI specifications directly in CI and failing the build when breaking changes are detected.
Example CI output:
❌ Breaking API change detected
Removed endpoint: DELETE /users/{id}
By validating API changes automatically during pull requests, teams can catch compatibility issues before deployment.
Example Implementation
A simple implementation using GitHub Actions is available here:
https://github.com/delimit-ai/delimit-action
It compares OpenAPI or Swagger specifications between commits and flags breaking changes during CI runs.
Why This Matters
APIs often serve as contracts between teams, services, and external integrations.
Automated contract validation helps ensure that changes to the API remain compatible with existing clients.
As APIs grow larger and more interconnected, having automated guardrails becomes increasingly important for maintaining stability.
Discussion
How do your teams handle API contract validation?
- OpenAPI diff tools
- contract testing
- schema versioning
- manual review
Curious to hear what approaches others are using.
Top comments (1)
A lot of teams rely on manual OpenAPI reviews, but those can be difficult once specs get large.
Curious if anyone here is using contract testing or schema diff tools in CI.