Mastering API Versioning in Spring Boot 4.0 with Spring Framework 7

Basic Usage: RequestMapping version attribute

Spring Framework 7.0 adds a

version

attribute to

@RequestMapping

and its derived annotations, making version control concise.

<code>@RequestMapping
@RestController
public class DemoController {
    @GetMapping(version = "1")
    public String version1() {
        return "API Version 1.0.0";
    }

    @GetMapping(version = "2")
    public String version2() {
        return "API Version 2.0.0";
    }
}
</code>

Version Parsing Configuration: ApiVersionConfigurer

Implement

WebMvcConfigurer

and override

configureApiVersioning

to customize version resolution, e.g., using request parameters.

<code>@Configuration
public class WebConfiguration implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        // Method 1: request parameter (default "version")
        configurer.useRequestParam("version");
        // Method 2: request header
        // configurer.useRequestHeader("API-Version");
        // Method 3: path variable
        // configurer.usePathVariable("version");
    }
}
</code>

Common Version Control Strategies

Request Parameter :

?version=1

Request Header :

API-Version: 1

Path Variable :

/api/v1/users

Accept Header :

Accept: application/vnd.api+json;version=1

Call Test

Testing with request parameters:

<code># Call version 1
curl "http://localhost:8080/?version=1"
# Output: API Version 1.0.0

# Call version 2
curl "http://localhost:8080/?version=2"
# Output: API Version 2.0.0

# No version specified
curl "http://localhost:8080/"
</code>

Advanced Configuration: Custom Version Resolver

For complex scenarios, implement a custom

ApiVersionResolver

to resolve versions from user‑agent, client IP, or other business rules.

<code>@Configuration
public class WebConfiguration implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useVersionResolver(new ApiVersionResolver() {
            @Override
            @Nullable
            String resolveVersion(HttpServletRequest request) {
                // Example 1: from User-Agent
                String userAgent = request.getHeader("User-Agent");
                if (userAgent != null && userAgent.contains("mobile")) {
                    return "mobile";
                }
                // Example 2: based on client IP
                String clientIp = getClientIp(request);
                if (isTestEnvironment(clientIp)) {
                    return "beta";
                }
                // Default version
                return "1";
            }
        });
    }
}
</code>

Summary

Incoming requests are processed by

RequestMappingHandlerMapping

to locate the appropriate controller method.

The handler invokes

ApiVersionStrategy

to extract the API version from the request.

After obtaining the version, candidate controller methods are filtered.

The best‑matching method is finally selected and invoked.

Spring Boot 4.0’s native version‑control support enables developers to manage API evolution gracefully, improving maintainability and user experience.