Response Body Transformation

Tyk enables you to modify the payload of API responses received from your upstream services before they are passed on to the client that originated the request. This makes it easy to transform between payload data formats or to expose legacy APIs using newer schema models without having to change any client implementations. This middleware is only applicable to endpoints that return a body with the response.

With the body transform middleware you can modify XML or JSON formatted payloads to ensure that the response contains the information required by your upstream service. You can enrich the response by adding contextual data that is held by Tyk but not included in the original response from the upstream.

This middleware changes only the payload and not the headers. You can, however, combine this with the Response Header Transform to apply more complex transformation to responses.

There is a closely related Request Body Transform middleware that provides the same functionality on the request sent by the client prior to it being proxied to the upstream.

When to use the Response Body Transformation middleware

Maintaining compatibility with legacy clients

Sometimes you might have a legacy API and need to migrate the transactions to a new upstream service but do not want to upgrade all the existing clients to the newer upstream API. Using response body transformation, you can convert the new format that your upstream services provide into legacy XML or JSON expected by the clients.

Shaping responses for different devices

You can detect the client device types via headers or context variables and transform the response payload to optimise it for that particular device. For example, you might optimise the response content for mobile apps.

SOAP to REST translation

A common use of the response body transform middleware is when surfacing a legacy SOAP service with a REST API. Full details of how to perform this conversion using Tyk are provided here.

How body transformation works

Tyk’s body transform middleware uses the Go template language to parse and modify the provided input. We have bundled the Sprig Library (v3) which provides over 70 pre-written functions for transformations to assist the creation of powerful Go templates to transform your API responses.

The Go template can be defined within the API Definition or can be read from a file that is accessible to Tyk, for example alongside your error templates.

We have provided more detail, links to reference material and some examples of the use of Go templating here.

Supported response body formats

The body transformation middleware can modify response payloads in the following formats:

• JSON
• XML

When working with JSON format data, the middleware will unmarshal the data into a data structure, and then make that data available to the template in dot-notation.

Data accessible to the middleware

The middleware has direct access to the response body and also to dynamic data as follows:

• Context variables, extracted from the request at the start of the middleware chain, can be injected into the template using the ._tyk_context.KEYNAME namespace
• Session metadata, from the Tyk Session Object linked to the request, can be injected into the template using the ._tyk_meta.KEYNAME namespace
• Inbound form or query data can be accessed through the ._tyk_context.request_data namespace where it will be available in as a key:[]value map
• values from key-value (KV) storage can be injected into the template using the notation appropriate to the location of the KV store

The response body transform middleware can iterate through list indices in dynamic data so, for example, calling {{ index ._tyk_context.request_data.variablename 0 }} in a template will expose the first entry in the request_data.variablename key/value array.

Automatic XML <-> JSON Transformation

A very common transformation that is applied in the API Gateway is to convert between XML and JSON formatted body content.

The Response Body Transform supports two helper functions that you can use in your Go templates to facilitate this:

• jsonMarshal performs JSON style character escaping on an XML field and, for complex objects, serialises them to a JSON string (example)
• xmlMarshal performs the equivalent conversion from JSON to XML (example)

If you’re using Tyk OAS APIs, then you can find details and examples of how to configure the response body transformation middleware here.

If you’re using Tyk Classic APIs, then you can find details and examples of how to configure the response body transformation middleware here.