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.

@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";
    }
}

Version Parsing Configuration: ApiVersionConfigurer

Implement WebMvcConfigurer and override configureApiVersioning to customize version resolution, e.g., using request parameters.

@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");
    }
}

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:

# 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/"

Advanced Configuration: Custom Version Resolver

For complex scenarios, implement a custom ApiVersionResolver to resolve versions from user‑agent, client IP, or other business rules.

@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";
            }
        });
    }
}

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.