API Versioning Strategies in Production: Breaking Changes & Deprecation

APIs are contracts. Breaking a contract without warning breaks every consumer that depends on it — mobile apps, partner integrations, internal microservices, and third-party developers. The engineering discipline of API versioning is how you evolve your API without breaking your ecosystem, and it requires as much design investment as the API itself.

Part of the Software Engineering Excellence Series.

Introduction

APIs that never change are APIs that never improve. But APIs that change without warning are APIs that break production systems at 2 AM. The art of API versioning is managing the tension between evolution and stability — giving the API team the freedom to improve the contract while giving consumers the stability to build reliable integrations.

This is not a theoretical concern. In 2023, Twilio removed a deprecated API endpoint and broke integrations for thousands of customers who had not migrated. Stripe accidentally changed a date format in a response field, breaking parsers across multiple client libraries. GitHub changed the default branch name from master to main in their API responses and caused CI/CD breakages across thousands of pipelines. Each of these was a breaking change that could have been managed better.

Real-World Problem: The Mobile App That Could Not Be Force-Updated

An e-commerce mobile app team needed to refactor the product search API — the old response shape was deeply nested and causing performance issues. Their search endpoint returned a complex JSON structure that mobile clients had parsed directly into model objects. The engineering team made the change in a single deployment, updating the response shape to a flatter structure. The web app team caught it immediately and updated their parser. But the iOS and Android teams discovered the breakage 48 hours later — after a significant percentage of their user base had encountered JSON deserialization errors, app crashes, and reported bugs. The root cause: no API versioning strategy meant no way to run old and new response shapes simultaneously.

Breaking vs Non-Breaking Changes

Rigorously classifying changes is the foundation of good API versioning. Non-breaking (backward-compatible) changes: adding a new optional field to a response, adding a new optional request parameter, adding a new endpoint, adding a new value to an enum (with caution — consumers that switch on enum values will miss it), relaxing validation (accepting more input formats). Breaking changes: removing a field from a response, renaming a field, changing a field's type (string to integer, object to array), adding a required request field, changing authentication schemes, changing URL structure, changing error response formats, removing an endpoint, changing HTTP method semantics.

The subtler breaking changes that teams miss: changing the order of fields in an array when consumers depend on order; changing a nullable field to non-nullable; changing pagination behavior (page-based to cursor-based); changing the meaning of an existing field without changing its name; changing rate limit headers; changing redirect behavior.

Versioning Strategies

URI Path Versioning

The most common and most cacheable: /api/v1/products, /api/v2/products. Advantages: version is explicit and visible in logs, API gateways and CDNs can route by path, easy to test and document, easy to deprecate (HTTP 410 Gone for removed versions). Disadvantages: violates REST purity (the URL should identify a resource, not a version), requires URL changes in all clients when upgrading. Used by: Twitter/X, YouTube Data API, GitHub API, Stripe.

Header Versioning

Version specified in a request header: API-Version: 2026-03-01 (date-based, used by Stripe) or Accept: application/vnd.myapi.v2+json (content negotiation). Advantages: URL remains clean, supports fine-grained versioning per resource type (via content negotiation). Disadvantages: not visible in browser URL bar, harder to test with simple HTTP clients, CDN caching requires careful Vary header configuration to avoid serving cached v1 responses to v2 clients. Used by: Stripe (date versioning), GitHub (content negotiation), Salesforce.

Query Parameter Versioning

Version as a query parameter: /api/products?version=2. Easy to implement, easy to test, but pollutes URLs and is considered less clean. Used by some older APIs but not recommended for new designs due to caching complications (query parameters often uncached by default CDN configurations).

Date-Based Versioning (Stripe Model)

Stripe's approach is the most sophisticated: each API key has a locked version date, and every breaking change is associated with a date. When Stripe makes a breaking change, it applies only to API requests with a version date after the change. Existing customers' API keys continue receiving the old behavior indefinitely. Customers can test the new behavior by passing the newer date header, then "upgrade" their API key version when ready. This approach is operationally complex (the server must maintain behavior for every historical version) but provides the best developer experience.

Implementation in Spring Boot

URI versioning with a custom RequestMappingHandlerMapping: annotate controllers with @RequestMapping("/api/v1/products") and @RequestMapping("/api/v2/products"). For header versioning, use a custom condition annotation backed by a RequestCondition implementation that inspects the API-Version header. Spring Boot's @RequestHeader can also be used with a default value to serve v1 behavior when no version header is present.

For content negotiation versioning, configure ContentNegotiationStrategy to resolve the version from the Accept header. The cleanest approach for large APIs: use a version-aware request filter that extracts the version and adds it to the request context, then use a HandlerMethodArgumentResolver to inject the version into controller methods.

Deprecation Process: The Four-Phase Runbook

Phase 1 — Announce (T-90 days minimum): Add a Deprecation: true response header and a Sunset: <date> header (RFC 8594) to all responses from deprecated endpoints. Publish deprecation notice in API changelog, developer portal, and via direct email to API key holders who have used the deprecated endpoint in the last 90 days. Log all requests to deprecated endpoints for migration tracking.

Phase 2 — Monitor (T-90 to T-30): Track unique API key identifiers calling deprecated endpoints. Build a dashboard showing migration progress. Reach out proactively to customers still using deprecated endpoints with migration guides. Provide a migration script or automated migration tool where possible.

Phase 3 — Throttle (T-30 to T-0): Gradually reduce rate limits on deprecated endpoints to create urgency without immediate breakage. Return HTTP 299 Warning headers with deprecation message in every response. Consider blocking new API key creation from accessing deprecated endpoints.

Phase 4 — Remove (T-0 and after): Return HTTP 410 Gone with a detailed error message including the migration guide URL. Keep the 410 response for at least 6 months — never immediately return 404, which obscures that the endpoint existed and was intentionally removed.

Consumer-Driven Contract Testing

Consumer-driven contracts (CDC) with Pact prevent breaking changes from reaching production. The model: each consumer defines a "pact" — a set of expectations about the producer's API (request structure, response fields, HTTP status codes). The producer runs these pacts as tests in CI. If the producer makes a change that breaks any consumer's pact, the CI pipeline fails before deployment. This inverts the traditional testing model — instead of the producer writing tests that it believes are correct, consumers define what they need, and the producer is contractually obligated to satisfy those needs.

Spring Boot integration: add spring-cloud-contract or pact-jvm-provider-spring to the producer's dependencies. Consumer teams publish their pacts to a Pact Broker (open-source or PactFlow). Producer CI fetches pacts from the broker and verifies them on every build. Can-I-Deploy checks in CD pipelines ensure no deployment proceeds until all consumer contracts pass.

API Gateway Versioning

For microservices, an API gateway provides a natural version routing layer. Configure routes: /api/v1/* → service-v1 (old stable version), /api/v2/* → service-v2 (new version). This decouples the versioning infrastructure from the service implementation and allows gradual migration via traffic weighting. AWS API Gateway, Kong, and Nginx all support path-based routing with traffic splitting for A/B versioning during migrations.

GraphQL and gRPC Versioning

GraphQL: GraphQL's schema evolution approach prefers additive changes over versioning. The @deprecated directive marks fields for removal. Introspection queries let clients discover deprecated fields. For breaking changes, field aliases and resolver multiplexing can serve old behavior under the new schema shape. URL-based versioning is considered anti-pattern in GraphQL — the schema is the version.

gRPC/Protocol Buffers: Protobuf is designed for forward and backward compatibility. Adding new fields (with new field numbers) is always backward-compatible. Removing fields requires reserving the field number to prevent reuse. For breaking type changes, add a new field alongside the old one (parallel fields pattern) and migrate consumers before removing the old field. Use proto3's optional keyword to distinguish between absent and default-value fields.

Trade-offs

Maintaining multiple API versions in parallel increases operational overhead: code duplication (or parameterization), test surface area, documentation burden, and the cognitive overhead of understanding which behavior applies to which version. The longer you maintain deprecated versions, the higher this cost. The most pragmatic approach: set a maximum support window (e.g., 12 months from deprecation announcement) and stick to it. Never extend it for convenience — it teaches consumers that deadlines are negotiable and encourages procrastination on migrations.

Key Takeaways

• Classify every change as breaking or non-breaking before merging — this discipline prevents accidental breakage
• URI path versioning is the most practical for most teams; header versioning is cleaner but harder to cache and test
• The deprecation runbook (announce → monitor → throttle → remove) is the minimum viable process for any public API
• Consumer-driven contract testing with Pact catches breaking changes in CI before deployment
• Always return HTTP 410 Gone (not 404) for removed endpoints, and maintain it for at least 6 months
• The Sunset HTTP header (RFC 8594) is the machine-readable deprecation standard — use it

Conclusion

API versioning is ultimately a product and organizational discipline as much as a technical one. The best versioning strategy is the one your team will actually follow consistently — with clear ownership of deprecation communication, automated contract testing in CI, and API gateway routing that insulates consumers from service-level changes. Invest in these processes early, before your API has external consumers, so that the discipline is established culture by the time breaking changes become high-stakes.

← Back to Blog