Understanding API Breaking Changes

When a third-party API you depend on introduces a breaking change, it can cascade through your system — causing failed requests, data inconsistencies, or customer-facing errors. This guide explains what constitutes a breaking change, how to detect them early, and strategies for handling API migrations.

What Is a Breaking Change?

A breaking change is any modification to an API that can cause existing consumers to fail without code changes. The key principle is backwards compatibility: can existing code continue to work after the change?

Common Types of Breaking Changes

How OpenAPI Diffs Detect Breaking Changes

Many modern APIs publish an OpenAPI specification that describes their endpoints, schemas, and data types in a machine-readable format. By comparing two versions of an OpenAPI spec, tools can automatically identify every change and classify it by impact.

Brief Stack uses oasdiff, an OpenAPI diff engine, to compare consecutive specification versions. The diff output is then classified using the following severity model:

How Top API Platforms Handle Versioning

Stripe: Date-Based Versioning

Stripe uses date-based API versions (e.g., 2024-12-18). When you create an account, your API version is pinned. Breaking changes only affect you when you explicitly upgrade your API version. Stripe also provides a changelog and migration guide for each version.

GitHub: URL Path Versioning

GitHub uses URL-based versioning for their REST API (e.g., /v3/repos) and date-based versions for their GraphQL API. They announce breaking changes through their changelog and provide deprecation notices well in advance.

Twilio: Major Version Bumps

Twilio uses traditional major version numbers for breaking changes. Their API specifications are published as OpenAPI documents, making it possible to track changes at the schema level.

Strategies for Safe API Migrations

1. Monitor Before You Migrate

Subscribe to API changelogs, or use automated tools like Brief Stack to track specification changes. Know about breaking changes before they affect your production system.

2. Use Adapter Patterns

Wrap third-party API calls in an adapter layer. When the API changes, you only need to update the adapter — not every call site in your codebase.

// Instead of calling the API directly everywhere:
const data = await stripe.customers.create({ email });

// Use an adapter:
const data = await paymentService.createCustomer({ email });
// The adapter handles version differences internally

3. Test with Dual Reads

When migrating to a new API version, implement dual reads: call both the old and new versions, compare results, and log discrepancies. This validates correctness before you fully switch over.

4. Implement Gradual Rollout

Don't switch all traffic to the new API version at once. Use feature flags or traffic splitting to gradually shift traffic, monitoring for errors at each stage.

5. Pin API Versions

Always specify the API version explicitly in your requests. Never rely on the "latest" version, as it can change without notice.

Key Takeaways

• ✅ Not all API changes are breaking — additive changes are usually safe
• ✅ OpenAPI specs enable automated change detection at the schema level
• ✅ Pin your API versions and upgrade deliberately
• ✅ Wrap API calls in adapter layers for easier migration
• ✅ Test migrations with dual reads before full switchover
• ✅ Monitor for breaking changes proactively, don't wait for failures