Skip to main content

Request/Response Transformation Between Legacy and Modern APIs Using Visual Workflows

Your modern clients shouldn't need to speak XML, camelCase field names shouldn't depend on backend conventions, and a legacy backend upgrade shouldn't be a client migration project. Here's how the gateway handles translation.

  • workflows
  • api-management
  • legacy
  • developer-experience
Zerq team

Legacy backends do not go away. They are too deeply embedded in business processes, too risky to rewrite, and too expensive to migrate. But the clients consuming them — mobile apps, partner integrations, modern microservices — expect JSON, consistent field naming, predictable error structures, and clean authentication flows.

The traditional answer is to wrap the legacy backend in an adapter service: a dedicated microservice that translates between the old and new interface. That works, but it creates a new deployment unit, a new failure point, and a maintenance burden that belongs to whichever team drew the short straw.

The gateway layer is the more natural place for this translation — and with visual workflow configuration, it does not require writing the adapter.

What transformation actually means at the gateway

Transformation at the gateway level covers four categories:

Protocol and format translation. Legacy backends often speak XML, SOAP, or custom binary protocols. Modern clients expect JSON over HTTP. The gateway can receive a JSON request from the client, convert it to the format the backend expects, call the backend, and convert the response back to JSON — without either side knowing about the other's format.

Field mapping and renaming. A legacy system may return CustomerID where your modern API convention is customerId, or acct_bal where clients expect accountBalance. The gateway maps fields from the backend's naming to the client-facing naming, decoupling clients from the backend's internal conventions.

Type coercion and data normalisation. Legacy systems often return dates as Unix timestamps, or in regional formats (DD/MM/YYYY), or as strings where clients expect ISO 8601. They return amounts as strings with currency symbols rather than numeric values. Booleans arrive as "Y" and "N" rather than true and false. The gateway normalises these to the types your API contract specifies.

Request enrichment. Modern clients may not know about legacy backend requirements: specific headers, correlation IDs, routing parameters that the legacy system needs but the client should not have to supply. The gateway adds these to outbound requests before they reach the backend.

The XML-to-JSON pattern

SOAP and XML backends are the most common legacy transformation use case. A client sends a clean JSON request; the gateway translates it to a SOAP envelope; the backend responds with XML; the gateway translates the response back to JSON.

The transformation workflow for this pattern:

[Incoming: POST /api/payments/initiate]
[Body: JSON {"amount": 150.00, "currency": "GBP", "recipient": "..."}]
         |
[Transform Request: JSON → SOAP envelope]
[Set Content-Type: text/xml]
[Set SOAPAction header]
         |
[Call: legacy-payment-service:8443/payments]
         |
[Transform Response: XML → JSON]
[Map: PaymentResponse.TransactionID → transactionId]
[Map: PaymentResponse.Status → status]
[Map: PaymentResponse.Timestamp → processedAt (ISO 8601)]
         |
[Return: 200 JSON {"transactionId": "...", "status": "...", "processedAt": "..."}]

The client sees a clean REST API. The legacy backend receives the SOAP request format it has always expected. Neither side is aware of the translation layer.

Field mapping for backend modernisation without client migration

One of the most disruptive moments in API lifecycle management is when a backend changes its response structure. Fields get renamed, data types change, nested objects are flattened or restructured. Without a transformation layer, every client that consumes the API needs to be updated simultaneously — which, in practice, means a coordinated migration that takes months.

With a gateway transformation layer, you can change the backend's response structure and update the gateway mapping to maintain the old client-facing shape. Clients see no change. The backend can evolve. The migration happens at the transformation layer, not across all clients simultaneously.

When you are ready to expose the new shape to clients, you can introduce it as a versioned API — v2 — with the new field names and structure, served by the same backend through a different transformation mapping. V1 clients continue to receive the old shape. V2 clients receive the new one. Both transformations run in the same gateway workflow, pointing at the same backend.

Authentication translation

Legacy backends often use authentication mechanisms that modern clients should not need to implement. A SOAP backend may require WS-Security headers. An older REST service may use HTTP Basic authentication. An internal system may use a proprietary session token format.

Modern clients authenticate to the gateway using OAuth 2.0, API keys, or JWT. The gateway validates the client credential and then translates it to whatever the backend expects:

  • The gateway receives a Bearer token from the client, validates it, and adds a Basic authentication header to the outbound backend call using a stored service credential.
  • The gateway receives an API key, looks up the associated backend service account, and adds the WS-Security header the legacy SOAP service requires.
  • The gateway receives a JWT, extracts the user identifier, and adds a session cookie the legacy application server needs.

The client uses modern, secure authentication. The legacy backend receives the authentication format it was built for. The translation happens once, in the gateway, rather than in every client integration.

Normalising error responses from legacy systems

Legacy backends return errors in inconsistent formats: HTTP 200 with an error flag in the body, HTML error pages, plain-text messages, SOAP fault elements, custom error codes with no HTTP status mapping.

The gateway transformation handles this alongside response transformation:

Detect non-standard error conditions. Inspect the backend response for error indicators — a status: "FAILED" field in the body, a SOAP fault element, an HTTP 200 with an error flag — and treat them as errors even if the HTTP status code does not indicate failure.

Map to appropriate HTTP status codes. A legacy error code ERR_ACCOUNT_SUSPENDED maps to an HTTP 403. ERR_TIMEOUT maps to 503. ERR_VALIDATION maps to 400. The gateway translates the legacy error code to the correct HTTP semantics.

Format as standard error shape. The gateway returns a consistent error body to the client — not a SOAP fault XML document, not a plain text message, not whatever the legacy system produced. The client handles one error format across all APIs, regardless of what the backend returned.

When a new backend is ready: phasing out the transformation

Transformation workflows are not meant to be permanent. They are a bridge that allows legacy backends to serve modern clients while modernisation proceeds. The exit path is designed into the workflow from the start:

Phase 1: Full transformation. The new client-facing API is fully provided by the transformation workflow. Clients use the modern API shape. The legacy backend serves the traffic unchanged.

Phase 2: Canary to the new backend. A new, modern backend is deployed. The workflow routes a percentage of traffic to it — no transformation required, because the new backend already speaks the right format — while the remainder continues through the legacy path with transformation.

Phase 3: Full cutover. All traffic routes to the new backend. The transformation nodes are removed from the workflow. The legacy backend is decommissioned.

At every phase, clients see the same API. The transformation layer made the migration invisible to the consuming side.

What stays in the workflow vs what moves to a service

Gateway transformation workflows have clear limits. They are the right place for:

  • Format translation (JSON ↔ XML, field renaming, type coercion)
  • Header enrichment and authentication translation
  • Error normalisation and status code mapping
  • Simple conditional transformation (if field X is null, use default Y)

They are not the right place for:

  • Complex business logic that requires domain knowledge
  • Stateful transformations that require database lookups
  • Multi-step orchestration that involves calling the legacy backend multiple times to assemble a response

When transformation logic crosses into those categories, a lightweight adapter service is appropriate — but its scope should be narrow: the business logic that genuinely cannot live in configuration. The format translation, the field mapping, and the error normalisation stay in the gateway.

Zerq's workflow designer supports request and response transformation, field mapping, authentication translation, and error normalisation — configured visually, no adapter service required. See the workflow capabilities or request a demo to walk through your specific legacy integration and modernisation use case.

Request Enterprise DemoExplore capabilities