The Context: "The 3 AM Trigger"
It was December 2023. Our logistics client, "CargoStream" (name changed), decided to launch a completely rewritten Shipping API (v2). They updated their Spring Cloud Gateway to route any traffic with the /v2/ path prefix to the new Java 21 microservices.
The baigan problem? They didn't tell their biggest enterprise B2B partner. At 3 AM, the partner's automated system hit the /v1/ endpoint, exactly as it had done for three years. But the v1 services had been physically decommissioned to save AWS costs. The partner received a cascading wall of HTTP 404s, causing their global supply chain software to halt cargo loading operations in Singapore. The CEO was furious. You cannot simply turn off a v1 API. We needed a transparent depreciation and routing strategy that kept older clients alive without maintaining legacy codebases.
The Problem Statement
Our constraints for the API versioning architecture:
- Zero Legacy Code: We refuse to run the old v1 Spring Boot applications just to serve 2% of legacy traffic.
- Client Transparency: The legacy B2B partner must continue hitting
/v1/shippingperfectly without changing a single line of their code. - Maintainability: The v2 microservice must only contain v2 business logic; it cannot be polluted with
if (version == 1)conditional spaghetti.
Visual Architecture
The Core Logic / Process
Data Flow
We utilized advanced routing and body manipulation within Spring Cloud Gateway to implement a "Strangler Fig" pattern at the network edge.
When a modern client calls /v2/shipping, the Gateway simply proxies the request directly to the modern Shipping Service.
When the legacy B2B partner calls /v1/shipping, the Gateway intercepts it. First, a RewritePath filter changes the URL from /v1 to /v2. Second, we implemented a custom ModifyRequestBodyGatewayFilterFactory. This filter intercepts the incoming v1 JSON payload, maps the deprecated cargo_weight field to the new v2 totalWeightKg field dynamically in memory, and forwards the mutated request to the v2 service.
Concurrency & Locking
Because Spring Cloud Gateway is built on Project Reactor and Netty, modifying the request and response body requires careful memory management. You cannot simply block the thread to parse JSON. We utilized Jackson non-blocking parsers and Reactor's DataBuffer specifically to rewrite the JSON on the fly using Netty's event loop, strictly avoiding any thread starvation or locking.
Failure Modes
What happens if the v2 API returns a new field in its response that the v1 partner's strict JSON parser rejects?
We implemented a ModifyResponseBodyGatewayFilterFactory. As the v2 payload travels back through the Gateway to the v1 client, the filter strips out the newly added fields and down-casts the schema to perfectly match the old v1 Swagger definition. The partner's strict parser accepts it seamlessly. The legacy client is none the wiser.
The "Baigan" Take (Expert Insights)
Look, everyone thinks API versioning just means putting /v1/ or /v2/ in the URL. That's the easy part. The hard part is the data translation.
If you let your backend microservices handle the translation, your Java domains become terrifying. You end up with endpoints like createOrderV1 and createOrderV2 calling the same OrderService, packed with if(isLegacy) checks.
The baigan truth is that version capability adapters belong at the Edge. The API Gateway is the perfect place to "up-cast" incoming deprecated requests into your modern domain language, and "down-cast" outgoing responses back into the deprecated format. This allows your backend engineers to brutally delete the v1 code and focus entirely on the future, while the Gateway handles the past.
Performance Checklist
- Enforce API versioning strictly at the API Gateway routing layer.
- Implement non-blocking
ModifyRequestBodyfilters to upcast deprecated JSON payloads to the modern schema. - Implement non-blocking
ModifyResponseBodyfilters to strip modern fields and downcast formats for legacy clients. - Offload version translation logic entirely from the core microservices to the edge.