Spring Framework 7.0 Native API Versioning Support and Implementation Guide

API version control is a key practice in modern web development, allowing teams to evolve APIs without breaking existing clients.

Spring Framework 7.0 introduces native support for API versioning, providing built‑in mechanisms for routing and handling version‑specific requests.

Importance of API version control

Backward compatibility: Allows older clients to continue working after a new API version is released.

Smooth evolution: Provides a transition period for new features and major changes.

Clear contract: Explicitly marks the behavior of each API version, reducing confusion.

Common strategies include URI versioning, request‑header versioning, query‑parameter versioning, and media‑type (content‑negotiation) versioning.

Spring 7.0 API version control

Developers can now specify a version attribute on @RequestMapping (and its variants) to bind a handler method to a specific API version.

Implementation example

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @RequestMapping(value = "/api/users", version = "1.0")
    public ResponseEntity
> getUsersV1() {
        // version 1.0 implementation
        List
users = fetchUsersV1();
        return ResponseEntity.ok(users);
    }

    @RequestMapping(value = "/api/users", version = "2.0")
    public ResponseEntity
> getUsersV2() {
        // version 2.0 implementation
        List
users = fetchUsersV2();
        return ResponseEntity.ok(users);
    }
}

The endpoint /api/users will invoke the appropriate method based on the requested version (e.g., 1.0 or 2.0), which can be supplied via URI, header, or query parameter.

Version resolution flexibility

Spring parses the version from various sources such as path segments, request headers, or query parameters. Custom resolvers can be created by implementing the ApiVersionResolver interface.

@FunctionalInterface
public interface ApiVersionResolver {
    @Nullable
    String resolveVersion(ServerWebExchange exchange);
}

Example of a path‑segment resolver:

public class PathApiVersionResolver implements ApiVersionResolver {

    private final int pathSegmentIndex;

    public PathApiVersionResolver(int pathSegmentIndex) {
        Assert.isTrue(pathSegmentIndex >= 0, "'pathSegmentIndex' must be >= 0");
        this.pathSegmentIndex = pathSegmentIndex;
    }

    @Override
    @Nullable
    public String resolveVersion(ServerWebExchange exchange) {
        int i = 0;
        for (PathContainer.Element e : exchange.getRequest().getPath().pathWithinApplication().elements()) {
            if (e instanceof PathContainer.PathSegment && i++ == this.pathSegmentIndex) {
                return e.value();
            }
        }
        return null;
    }
}

Spring also provides DefaultApiVersionStrategy and VersionRequestCondition to compare, validate, and match versions during request mapping.

Client‑side API versioning

Using WebClient , callers can set the Accept header to a versioned media type, ensuring the request targets the desired API version.

public class UserClient {

    private final WebClient webClient;

    public UserClient(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder.baseUrl("http://example.com").build();
    }

    public Mono
> getUsersV1() {
        return webClient.get()
                .uri("/api/users")
                .accept(MediaType.valueOf("application/vnd.company.app-v1+json"))
                .retrieve()
                .bodyToMono(List.class);
    }
}

Spring 7.0’s flexible version‑parsing mechanisms allow developers to choose the most suitable strategy for their project, from simple URI versioning to sophisticated content‑negotiation approaches.

Conclusion

Native API versioning in Spring Framework 7.0 provides a standardized, powerful toolset for managing API evolution, improving the robustness and maintainability of Spring‑based services.