Interface ApiVersionStrategy

All Known Implementing Classes:
DefaultApiVersionStrategy
public interface ApiVersionStrategy
The main component that encapsulates configuration preferences and strategies to manage API versioning for an application.
Since:
7.0
Author:
Rossen Stoyanchev
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    @Nullable Comparable<?>
    getDefaultVersion()
    Return a default version to use for requests that don't specify one.
    void
    handleDeprecations(Comparable<?> version, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    Check if the requested API version is deprecated, and if so handle it accordingly, e.g.
    Comparable<?>
    parseVersion(String version)
    Parse the version of a request into an Object.
    default @Nullable Comparable<?>
    resolveParseAndValidateVersion(jakarta.servlet.http.HttpServletRequest request)
    Convenience method to return the parsed and validated request version, or the default version if configured.
    @Nullable String
    resolveVersion(jakarta.servlet.http.HttpServletRequest request)
    Resolve the version value from a request, e.g.
    void
    validateVersion(@Nullable Comparable<?> requestVersion, jakarta.servlet.http.HttpServletRequest request)
    Validate a request version, including required and supported version checks.

  • Method Details

    • resolveVersion

      @Nullable String resolveVersion(jakarta.servlet.http.HttpServletRequest request)
      Resolve the version value from a request, e.g. from a request header.
      Parameters:
      request - the current request
      Returns:
      the version, if present or null
      See Also:

    • parseVersion

      Comparable<?> parseVersion(String version)
      Parse the version of a request into an Object.
      Parameters:
      version - the value to parse
      Returns:
      an Object that represents the version
      See Also:

    • validateVersion

      void validateVersion(@Nullable Comparable<?> requestVersion, jakarta.servlet.http.HttpServletRequest request) throws MissingApiVersionException, InvalidApiVersionException
      Validate a request version, including required and supported version checks.
      Parameters:
      requestVersion - the version to validate
      request - the request
      Throws:
      MissingApiVersionException - if the version is required, but not specified
      InvalidApiVersionException - if the version is not supported

    • getDefaultVersion

      @Nullable Comparable<?> getDefaultVersion()
      Return a default version to use for requests that don't specify one.

    • resolveParseAndValidateVersion

      default @Nullable Comparable<?> resolveParseAndValidateVersion(jakarta.servlet.http.HttpServletRequest request)
      Convenience method to return the parsed and validated request version, or the default version if configured.
      Parameters:
      request - the current request
      Returns:
      the parsed request version, or the default version

    • handleDeprecations

      void handleDeprecations(Comparable<?> version, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
      Check if the requested API version is deprecated, and if so handle it accordingly, e.g. by setting response headers to signal the deprecation, to specify relevant dates and provide links to further details.
      Parameters:
      version - the resolved and parsed request version
      request - the current request
      response - the current response
      See Also: