Spring Boot REST API Versioning

Yes. Starting with /api/v1/..., or a version header, costs nothing today and saves a painful change later. If your first release has no version, introducing v2 means either treating the unversioned URLs as an implicit v1, which is confusing, or breaking every existing client.

Many APIs never need a v2, and that is fine: the v1 simply stays.

For public URLs, use whole numbers only: v1, v2, v3. A new number should mean “this contract is incompatible with the previous one”, which happens rarely.

Compatible improvements, such as new fields, do not need a new public version at all. If you want finer tracking, keep it internally, for example in your changelog or with Spring Framework 7’s semantic versions in a header, but keep the public URL simple.

As few as possible, typically two: the current version and the previous one. Every extra version means more code to maintain, test and secure, and every bug fix may need to be checked in each version.

A clear policy helps everyone, for example: “a version is supported for 12 months after its successor is released”. Publish it, so clients can plan their upgrades.

Usually yes, because services are deployed independently. During a rolling deployment, an old version of service A can call a new version of service B, or the other way round.

Internally, it is often enough to design every change to be backward compatible: add fields instead of renaming them, and remove old fields only once no caller uses them. Formal version numbers become necessary when a breaking change cannot be avoided, or when many teams depend on the service.

Versioning the whole API, so that /api/v2/... applies to every endpoint, is simpler for clients: they pick one version and use it everywhere. The downside is that v2 may contain many endpoints that are identical to v1.

Per-resource versioning, for example with media types, lets each resource evolve on its own, but clients must track a version for every resource. Spring Framework 7’s baseline versions, such as "2.0+", offer a middle way: one API version number, without duplicating endpoints that did not change.

A gateway can route requests by version, which is useful when a new version is served by a different deployment:

spring:
  cloud:
    gateway:
      routes:
        - id: customers-v1
          uri: http://customer-service-v1:8080
          predicates:
            - Path=/api/v1/customers/**
        - id: customers-v2
          uri: http://customer-service-v2:8080
          predicates:
            - Path=/api/v2/customers/**

Header-based versions can be routed with a Header predicate in the same way. The gateway is also a good place to measure traffic per version and to add deprecation headers centrally. See the API Gateway Pattern.

All versions should share the same database and schema. The differences belong in the mapping layer: each version’s DTO is built from, or converted to, the same entities.

When the schema itself must change, make the change compatible with every supported version, using the expand and contract approach: add new columns first, keep old ones while old versions need them, and remove them only after those versions are retired. The Database Migration tutorial shows how.

Both. A breaking change in what clients send is just as harmful as one in what they receive. If v2 requires firstName and lastName, v1 clients still send name, so each version needs its own request DTO:

public record CreateCustomerV1(@NotBlank String name, @Email String email) { }

public record CreateCustomerV2(@NotBlank String firstName,
                               @NotBlank String lastName,
                               @Email String email) { }

Both are converted to the same internal command before reaching the service, as shown in section 11.

Caches, such as CDNs and browser caches, normally store responses by URL. With header versioning, v1 and v2 share the same URL, so a cache could return a v1 response to a v2 client. Tell caches that the response depends on the header:

return ResponseEntity.ok()
        .header(HttpHeaders.VARY, "X-API-Version")
        .body(CustomerV2.from(customer));

The same applies to media type versioning, with Vary: Accept. URI versioning avoids this issue entirely, which is one reason it is so popular.

A clear client error with a helpful message:

• URI versioning: an unknown path like /api/v9/... naturally returns 404 Not Found.
• Header or parameter versioning: return 400 Bad Request, explaining which versions are supported. Spring Framework 7’s built-in support does this automatically.

{
  "title": "Unsupported API version",
  "status": 400,
  "detail": "API version 9 is not supported. Supported versions: 1, 2."
}

It is convenient, but think about which default you choose:

• Default to the oldest supported version: existing clients that never sent a version keep working. This is the safer choice for public APIs.
• Default to the latest version: convenient for new clients, but every new release silently changes what unversioned clients receive, which may break them.

Many teams make the version required for new integrations, and keep a default only for clients from before versioning was introduced.

Partly. In semantic versioning (major.minor.patch), only the major number signals incompatible changes, and that is exactly what an API version needs to express to clients.

Minor and patch numbers are useful internally, for release notes and for Spring Framework 7’s baseline matching, but clients rarely need to request them. A practical rule: clients choose the major version; everything compatible within it reaches them automatically.

In GraphQL, each client asks for exactly the fields it needs. Adding fields never affects existing clients, and old fields can be marked @deprecated in the schema, which tools display as a warning, until nobody requests them anymore.

REST APIs can borrow this idea: prefer adding over changing, mark old fields as deprecated in your documentation, and track whether clients still use them. That way, a new version becomes necessary much less often.

Measure it. Record the version with every request, together with a client identifier such as an API key or application name:

@Component
public class ApiVersionMetricsFilter extends OncePerRequestFilter {

    private final MeterRegistry registry;

    public ApiVersionMetricsFilter(MeterRegistry registry) {
        this.registry = registry;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String version = Optional.ofNullable(request.getHeader("X-API-Version")).orElse("none");
        String client = Optional.ofNullable(request.getHeader("X-Client-Id")).orElse("unknown");
        registry.counter("api.requests", "version", version, "client", client).increment();
        chain.doFilter(request, response);
    }
}

A dashboard of requests per version and client shows exactly whom to contact before retiring a version. Keep the number of distinct client values limited, so the metric stays small.

It helps to group the version-specific classes, and only those:

com.javabytechie.shop.customer
├── Customer.java               <- shared entity
├── CustomerService.java        <- shared business logic
├── api/v1/
│   ├── CustomerControllerV1.java
│   └── CustomerV1.java
└── api/v2/
    ├── CustomerControllerV2.java
    └── CustomerV2.java

Never copy services, repositories or entities into versioned packages. If you find yourself doing that, the versions are drifting apart in their business rules, which is a much bigger problem than the API format.

Yes. The same concept, with the version attribute on mappings and a configurer in the WebFlux configuration, is available for reactive applications. On the client side, WebClient and RestClient can also add the version to outgoing requests automatically, so calling a versioned API needs no hand-written headers.

Events have the same problem as APIs, often worse, because old messages stay in the topic and may be read again later. Common approaches:

• Compatible evolution: only add optional fields, so old and new consumers can read every message.
• A schema registry with formats such as Avro or Protobuf, which checks compatibility before a new schema is accepted.
• A new event type or topic, such as CustomerCreatedV2, when a breaking change is unavoidable.

Possibly not. If your API serves only your own web front end, and both are always deployed together as one release, there is never an old client calling the new API, so a breaking change can be made in one step.

As soon as any of these applies, you need versioning or strictly compatible changes:

• Mobile apps, which users update at different times.
• Other teams’ services or external partners.
• Front end and back end deployed separately, or browsers keeping old pages open during a deployment.

Use several channels, because different people watch different places:

• A changelog listing every change, with migration steps for breaking ones.
• Updated API documentation for each version.
• Deprecation and Sunset headers on the old version, which automated tools can detect.
• Direct messages to the clients your metrics show are still on the old version.

A short migration guide, “what changed and exactly how to update”, gets clients to upgrade faster than any deadline.

Only for very small differences, and usually not even then. Code like this grows quickly and becomes hard to test:

// Avoid: every new version adds another branch
@GetMapping("/{id}")
public Object get(@PathVariable Long id, @RequestHeader("X-API-Version") int version) {
    Customer customer = customerService.findById(id);
    if (version == 1) {
        return CustomerV1.from(customer);
    }
    return CustomerV2.from(customer);
}

Separate methods or controllers per version, as shown in this tutorial, keep each contract readable, give each its own type-safe return value and documentation, and make it easy to delete an old version later.