|
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 Versioning
Spring MVC supports API versioning. This section provides an overview of the support and underlying strategies.
Please, see also related content in:
-
Configure API versioning in the MVC Config
-
Map requests to annotated controller methods with an API version
Client support for API versioning is available also in RestClient, WebClient, and
HTTP Service clients, as well as
for testing in MockMvc and WebTestClient.
ApiVersionStrategy
This is the central strategy for API versioning that holds all configured preferences related to versioning. It does the following:
-
Resolves versions from the requests via ApiVersionResolver
-
Parses raw version values into
Comparable<?>with an ApiVersionParser -
Validates request versions
-
Sends deprecation hints in the responses
ApiVersionStrategy helps to map requests to @RequestMapping controller methods,
and is initialized by the MVC config. Typically, applications do not interact
directly with it.
ApiVersionResolver
This strategy resolves the API version from a request. The MVC config provides built-in
options to resolve from a header, from a request parameter, or from the URL path.
You can also use a custom ApiVersionResolver.
ApiVersionParser
This strategy helps to parse raw version values into Comparable<?>, which helps to
compare, sort, and select versions. By default, the built-in SemanticApiVersionParser
parses a version into major, minor, and patch integer values. Minor and patch
values are set to 0 if not present.
Validation
If a request version is not supported, InvalidApiVersionException is raised resulting
in a 400 response. By default, the list of supported versions is initialized from declared
versions in annotated controller mappings, but you can turn that off through a flag in the
MVC config, and use only the versions configured explicitly in the config.
By default, a version is required when API versioning is enabled, and
MissingApiVersionException is raised resulting in a 400 response if not present.
You can make it optional in which case the most recent version is used.
You can also specify a default version to use.
ApiVersionDeprecationHandler
This strategy can be configured to send hints and information about deprecated versions to
clients via response headers. The built-in StandardApiVersionDeprecationHandler
can set the "Deprecation" "Sunset" headers and "Link" headers as defined in
RFC 9745 and
RFC 8594. You can also configure a custom
handler for different headers.
Request Mapping
ApiVersionStrategy supports the mapping of requests to annotated controller methods.
See API Version
for more details.
