support API versioning with multiple APIs in the same app

[nagyesta]

Hi Team,

I am really happy for the new API versioning support, because it helps me to eliminate a lot of unnecessary code. Thank you for this great feature!

Please see some details about my use-case below:

The app is a local emulator for Azure Key Vault, which can emulate:

• Multiple versions of Azure Key Vault (AKV) APIs (versions look like: 7.2, 7.3, 7.4, 7.5, 7.6)
• A token endpoint faking the behavior of the token endpoint used by the Azure Managed Identity (versions look like a date, e.g. 2018-02-01)

Both APIs evolve on their own, using different version formats but they are both using the same api-version query parameter.

In addition to this, I have some unversioned API endpoints of my own (where I rely on the default version functionality).

The two APIs are available using separate ports, AKV API endpoints are accessed through the secure (HTTPS) port and the token endpoint is available through an insecure (HTTP) port.

The issue I am facing

For this use-case, I need to provide both APIs in the same application, because this can save time and resources for the tests using the emulators, but it is important for me to strictly validate the version numbers of at least the AKV API (in order to provide a more perfect emulator) and preferably check the format of the versions of the token endpoint.

As far as I have understood, the current Spring implementation (7.0.2) does only support one versioning configuration per application context and it applies to all requests, without any possibility for:

1. Using different versioning schemes in the same app, especially using the same parameter
2. Applying the versioning config selectively, only for some specific URI paths/prefixes
3. Formulating version validation patterns (beyond defining a set of known versions) for the versioning when the API uses for example a date-based versioning instead of relying on a small set of predefined values.

How I use it for now

I have ended up implementing a custom version resolver for now to ignore the versioning in case of the requests received through the insecure port.

https://github.com/nagyesta/lowkey-vault/blob/220b25c599c1dfc5059a833950e7a3f09de3832a/lowkey-vault-app/src/main/java/com/github/nagyesta/lowkeyvault/context/OptionalQueryApiVersionResolver.java#L18-L25

This is a valid workaround, but not a nice one because it does not address the causes of my issues, just hides them.

How it could be solved

If the ApiVersionConfigurer would allow us to define a set of objects with the existing config, plus:

1. A request matcher to define the scope of the versioning
2. Instead of simply asking for the set of known versions, if we could provide a predicate to validate the versions (using a contains call like it is done today, or a regexp or any other means necessary if the user needs some special logic)

This would allow us to define multiple different versioning schemes for different path prefixes or even turn off versioning if it does not make sense for some part of the application, like my unversioned endpoints mentioned above.

Of course we would need to make sure that the request matchers cannot overlap, so an exception could be thrown in case multiple versioning configurations would match a request.

What do you think? Would this make sense?

Thank you in advance!

P.S.
I think this could also:

1. solve this issue with the error requests: When no API version is provided, /error requests also fail. #36058
2. let us ignore versioning for actuator endpoints easily
3. let us use different versionig schemes in monoliths hosting multiple APIs in one app

[rstoyanchev]

Thanks for the report.

One possibility is an ApiVersionStrategy that delegates to others based on a request path prefix. Another is multiple RequestMappingHandlerMappings each with its own ApiVersionStrategy.

If we see more demand for this, we can consider an enhancement to WebMvc config, but for now we'll leave that as more advanced use case.

This means you will need to configure the ApiVersionStrategys manually, and set them on RequestMappingHandlerMapping, but that should be quite straight forward, similar to what ApiVersionConfigurer does.

Closing for now, but we can reopen in the future as needed.

[nagyesta]

Makes sense, thank you!