API Versioning Strategies and the Cost of Each Approach
API versioning strategies compared: URL path, header, media type and query versions, the cost of each and how to avoid new versions.

The first time you change a response shape that a mobile app in the wild depends on, you learn what API versioning is for. The second time you learn what it costs. Every version you ship is a version you maintain, test, document and eventually have to retire against customers who do not want to move. The strategy question is not "URL or header" but "how do we change this API without breaking people, and how much of that are we willing to pay for". This post starts with the cheapest answer, which is to avoid a new version, then compares the four ways to carry a version, shows the Spring Framework 7 support for each, prices them, and covers the alternatives that sidestep the problem. Examples use Spring Boot 4 and Java 25.
First, avoid the version
Most changes do not need a new version. A response can evolve in place if you follow the rules that make a change backward compatible.
| Change | Safe in place? |
|---|---|
| Add an optional request field | Yes |
| Add a field to a response | Yes, if clients ignore unknown fields |
| Add a new endpoint | Yes |
| Remove or rename a field | No |
| Change a field's type or meaning | No |
| Make an optional request field required | No |
| Tighten validation | Usually no |
| Change an error code or status | No |
Hold clients to the matching duty: they must ignore fields they do not know, which in Jackson means not enabling FAIL_ON_UNKNOWN_PROPERTIES on the client side. If your API rules say "additive changes only within a version", then a new version is needed only for the breaking changes in the second half of the table. A team that is disciplined about this ships a new version every few years instead of every quarter. The design rules that keep changes additive are in REST API design rules for Java teams.
The four strategies
When you must version, there are four places to put the number.
URL path. GET /v2/orders/7. It is visible, easy to route, easy to test in a browser, and easy to cache. It also makes the version part of every resource's identity, so links and bookmarks break when the version retires.
Query parameter. GET /orders/7?version=2. Easy to add, but it pollutes cache keys and is easy to leave off by accident, which then falls to a default.
Request header. GET /orders/7 with X-API-Version: 2. Keeps URLs stable and clean, but clients and caches must remember the header, and it is invisible in logs unless you record it. A Vary header is needed for correct caching.
Media type. Accept: application/vnd.shop.order.v2+json. The purist's choice: a resource has one URL, and the representation is negotiated. It is the most correct and the most awkward for tooling, since many HTTP clients and API gateways handle custom media types poorly. The negotiation mechanics are in content negotiation in Spring MVC.
| Strategy | Visible | Cache-friendly | Tooling friendly | Retire a version |
|---|---|---|---|---|
| Path | Yes | Yes | Yes | Hard: URLs are public |
| Query | Yes | Needs care | Yes | Moderate |
| Header | No | Needs Vary | Moderate | Easy |
| Media type | No | Needs Vary | Hard | Easy |
There is no universally right row. Public APIs consumed by many unknown clients usually choose the path, because the cost of being obvious is smaller than the cost of support tickets from people who forgot a header.
Implementation in Spring
Spring Framework 7 supports API versioning directly. You declare how the version is read from a request once, and mark handlers with the version they serve.
package dev.javahacks.api;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
class ApiConfig implements WebMvcConfigurer {
@Override
public void configureApiVersioning(ApiVersionConfigurer configurer) {
configurer.useRequestHeader("X-API-Version")
.addSupportedVersions("1.0", "2.0")
.setDefaultVersion("1.0");
}
}Swap useRequestHeader for usePathSegment(0) to read the version from the first path segment, useQueryParam("version") for a query parameter, or useMediaTypeParameter(MediaType.APPLICATION_JSON, "version") for the media type. The strategy lives in one place, so changing it later does not touch handlers.
Mark the handlers:
@RestController
@RequestMapping("/orders")
class OrderController {
@GetMapping(path = "/{id}", version = "1.0")
OrderV1 getV1(@PathVariable long id) {
return new OrderV1(id, "Ada Lovelace", 4999);
}
@GetMapping(path = "/{id}", version = "2.0")
OrderV2 getV2(@PathVariable long id) {
return new OrderV2(id, new Customer("Ada", "Lovelace"), new Money(4999, "USD"));
}
}
record OrderV1(long id, String customerName, long totalCents) { }
record OrderV2(long id, Customer customer, Money total) { }
record Customer(String firstName, String lastName) { }
record Money(long amountCents, String currency) { }curl -s -H 'X-API-Version: 1.0' localhost:8080/orders/7
curl -s -H 'X-API-Version: 2.0' localhost:8080/orders/7
curl -s -i -H 'X-API-Version: 9.0' localhost:8080/orders/7 | head -1{"id":7,"customerName":"Ada Lovelace","totalCents":4999}
{"id":7,"customer":{"firstName":"Ada","lastName":"Lovelace"},"total":{"amountCents":4999,"currency":"USD"}}
HTTP/1.1 400An unsupported version gets a 400, because addSupportedVersions made the set explicit. Versions can be ranges: version = "1.2+" means that version and above, so a handler that did not change between versions need not be copied. The mechanism is described in the Spring MVC versioning reference. On older Spring, the same effect comes from @GetMapping(headers = "X-API-Version=2") or produces = "application/vnd.shop.v2+json", or from separate controllers under /v1 and /v2 packages.
What each version costs
The code above is cheap. The cost of a version is everything else.
Duplicate code. Two DTOs, two mappers, often two controllers. Keep the business logic shared and make the version a thin adapter at the edge, so OrderService knows nothing about versions. When v2 needs data v1 never had, that data lives in the domain regardless.
Duplicate tests. Every supported version needs its contract tests, and each bug fix needs checking against each version. A contract test suite per version, as covered in contract testing with Pact, keeps this from becoming manual.
Documentation. Two OpenAPI documents, two changelogs, two sets of examples.
Support and operations. Someone answers the question "which version is this client on?" Log the version on every request and chart it. You cannot retire a version you cannot see being used.
Retirement. The expensive part. Announce the end date in advance, send Deprecation and Sunset response headers (the latter is defined in RFC 8594), contact the remaining callers by name from your logs, then switch the old version to return 410 Gone before deleting the code:
response.setHeader("Deprecation", "true");
response.setHeader("Sunset", "Wed, 30 Sep 2027 00:00:00 GMT");
response.setHeader("Link", "</orders>; rel=\"successor-version\"");A reasonable policy: support at most two versions at once, and give at least six to twelve months of notice for external clients. A policy you cannot enforce is a wish.
Alternatives to versions
Some changes can be absorbed without a number.
- Expand and contract. Add the new field beside the old, populate both, migrate clients, then remove the old field in a later release after usage hits zero. The version number never changes.
- Feature negotiation. Clients opt into new behavior with a flag or an
includeparameter, and the default stays. - Tolerant readers. Both sides ignore what they do not understand, and add required fields only with a default.
- A different protocol for the hard case. Where clients need to choose their own fields, GraphQL moves the evolution problem to the schema; where services share schemas, a schema registry with compatibility rules works for events, as in versioning events with Avro and a schema registry. The trade-offs between styles are in REST versus GraphQL versus gRPC.
Choosing
If your clients are a few teams you can talk to, skip versioning: coordinate, expand and contract, and remove. If your API is public and long-lived, use the path version, since the visibility pays for itself, and keep it coarse (v1, v2, never v1.3.2). If your API is consumed by software you build and ship together, use the header, because the clients are under your control. Use the media type only when you already negotiate representations for other reasons.
When this does not apply
An internal API with a single consumer deployed in lockstep needs no versions, only a deployment order. An event stream needs schema compatibility rules, not URL versions. And a GraphQL API versions by deprecating fields, never by cutting a version. In each case the principle is the same: change in compatible steps, and spend the version number only when you truly cannot.


