Request Body Transformation

Tyk enables you to modify the payload of API requests before they are proxied to the upstream. 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 HTTP methods that can support a request body (i.e. PUT, POST or PATCH).

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 request by adding contextual data that is held by Tyk but not included in the original request from the client.

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

There is a closely related Response Body Transform middleware that provides the same functionality on the response from the upstream, prior to it being returned to the client.

When to use the Request 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 request body transformation, you can convert the incoming legacy XML or JSON request structure into a newer, cleaner JSON format that your upstream services expect.

Shaping requests received from different devices

You can detect device types via headers or context variables and transform the request payload to optimise it for that particular device. For example, you might send extra metadata to the upstream for mobile apps.

SOAP to REST translation

A common use of the request body transform middleware is to surface 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 requests.

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 request body formats

The body transformation middleware can modify request 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 request 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

Note that the request 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 Request 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 request body transformation middleware here.

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