This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Framework 6.2.8!

API Version

See equivalent in the Reactive stack

To enable API versioning, use the ApiVersionConfigurer callback of WebMvcConfigurer:

  • Java

  • Kotlin

@Configuration
public class WebConfiguration implements WebMvcConfigurer {

	@Override
	public void configureApiVersioning(ApiVersionConfigurer configurer) {
		configurer.useRequestHeader("X-API-Version");
	}
}
@Configuration
class WebConfiguration : WebMvcConfigurer {

	override fun configureApiVersioning(configurer: ApiVersionConfigurer) {
		configurer.useRequestHeader("X-API-Version")
	}
}

You can resolve the version through one of the built-in options listed below, or alternatively use a custom ApiVersionResolver:

  • Request header

  • Request parameter

  • Path segment

  • Media type parameter

When using a path segment, consider configuring a shared path prefix externally in Path Matching options.

By default, the version is parsed with SemanticVersionParser, but you can also configure a custom ApiVersionParser.

Supported versions are transparently detected from versions declared in request mappings for convenience, but you can turn that off through a flag in the MVC config, and consider only the versions configured explicitly in the config as supported. Requests with a version that is not supported are rejected with InvalidApiVersionException resulting in a 400 response.

You can set an ApiVersionDeprecationHandler to send information about deprecated versions to clients. The built-in standard handler can set "Deprecation", "Sunset", and "Link" headers based on RFC 9745 and RFC 8594.

Once API versioning is configured, you can begin to map requests to controller methods according to the request version.