Catching Breaking API Changes Before They Reach Production

Source: Dev.to

The Problem with Breaking API Changes

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.

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.

Common Breaking Changes

• 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.

Preventing Breaking Changes

One approach is to compare OpenAPI specifications directly in CI and fail 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.

Implementation

A simple implementation using GitHub Actions is available here:
https://github.com/delimit-ai/delimit-action

The action compares OpenAPI or Swagger specifications between commits and flags breaking changes during CI runs.

Why It Matters

APIs 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.