Version‑Aware Service Discovery, Load Balancing, and Gateway Routing for Spring API Versioning #1628
Description
Is your feature request related to a problem? Please describe.
Spring Framework now provides first‑class API Versioning support at the controller level, but Spring Cloud components (DiscoveryClient, LoadBalancer, Gateway) do not understand or use API version information.
Because of this, routing API requests to the correct service instance still requires manual Gateway route configuration for each version, or custom load‑balancer logic.
This becomes problematic when multiple instances of the same service support different sets of API versions. For example:
- Instance A supports API versions 1 and 2
- Instance B supports API version 1 only
Today, Spring Cloud cannot automatically route a request like API-Version: 2 to the correct instance without custom code or explicit Gateway routes. This limits the usefulness of Spring’s new API Versioning feature in microservice environments.
Describe the solution you'd like
I would like Spring Cloud to provide native, metadata‑driven, version‑aware routing across DiscoveryClient, LoadBalancer, and Gateway.
Specifically:
-
Service instances publish supported API versions as metadata
Examples: api-versions=1,2, api-versions=2+, etc -
Gateway extracts the requested API version
From URL (/v2/...), header (API-Version: 2), or media type. -
Spring Cloud LoadBalancer filters service instances
Only instances whose metadata includes the requested version should be eligible. -
Gateway routes remain generic
No need to define separate routes for each version.
Routing becomes dynamic and based on metadata + version negotiation.
This would allow Spring’s API Versioning to work end‑to‑end, from controllers to infrastructure, without manual configuration.
Describe alternatives you've considered
- Manual Gateway route definitions per version
Works but becomes unmanageable as versions grow. Requires redeploying Gateway for every version change. - Custom LoadBalancer implementation
Possible today, but every team must reinvent the same logic. A standardized solution would be more maintainable. - Using a service mesh (Istio/Envoy)
Provides version‑aware routing, but is far heavier than most Spring Cloud users need.
None of these alternatives integrate cleanly with Spring’s new API Versioning model.
Additional context
This feature would complete the story for API Versioning in Spring by enabling:
- Zero‑downtime version rollouts
- Coexistence of multiple API versions
- Dynamic scaling of versioned instances
- Backward compatibility without Gateway changes
- Cleaner microservice architecture
It aligns with how modern API gateways and service meshes handle version‑aware routing, but in a lightweight, Spring‑native way.
I’m happy to collaborate on design, prototype implementation, and documentation.