Using the Response Body Transform middleware with Tyk Classic APIs

Last updated: Sep 9, 2024 6 minutes read.

The response body transform middleware provides a way to modify the payload of API responses before they are returned to the client.

This middleware is configured in the Tyk Classic API Definition at the endpoint level. You can do this via the Tyk Dashboard API or in the API Designer.

If you’re using the newer Tyk OAS APIs, then check out the Tyk OAS page.

If you’re using Tyk Operator then check out the configuring the middleware in Tyk Operator section below.

Configuring the middleware in the Tyk Classic API Definition

To enable the middleware you must add a new transform_response object to the extended_paths section of your API definition.

The transform_response object has the following configuration:

path: the path to match on
method: this method to match on
template_data: details of the Go template to be applied for the transformation of the response body

The Go template is described in the template_data object by the following fields:

input_type: the format of input data the parser should expect (either xml or json)
enable_session: set this to true to make session metadata available to the transform template
template_mode: instructs the middleware to look for the template either in a file or in a base64 encoded blob; the actual file location (or base64 encoded template) is provided in template_source
template_source: if template_mode is set to file, this will be the path to the text file containing the template; if template_mode is set to blob, this will be a base64 encoded representation of your template

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
    "extended_paths": {
        "transform_response": [
            {
                "path": "/anything",
                "method": "POST",
                "template_data": {
                    "template_mode": "file",
                    "template_source": "./templates/transform_test.tmpl",
                    "input_type": "json",
                    "enable_session": true 
                }
            }
        ]
    }
}

In this example, the Response Body Transform middleware is directed to use the template located in the file at location ./templates/transform_test.tmpl. The input (pre-transformation) response payload will be json format and session metadata will be available for use in the transformation.

Note

Tyk will load and evaluate the template file when the Gateway starts up. If you modify the template, you will need to restart Tyk in order for the changes to take effect.

Note
Prior to Tyk 5.3, there was an additional step to enable response body transformation. You would need to add the following to the Tyk Classic API definition:

{
    "response_processors":[
        {"name": "response_body_transform"}
    ]
}

If using the Endpoint Designer in the Tyk Dashboard, this would be added automatically.

We removed the need to configure the response_processors element in Tyk 5.3.0.

Configuring the middleware in the API Designer

You can use the API Designer in the Tyk Dashboard to configure the response body transform middleware for your Tyk Classic API by following these steps.

Step 1: Add an endpoint for the path and select the plugin

From the Endpoint Designer add an endpoint that matches the path for which you want to perform the transformation. Select the Body Transforms plugin.

Endpoint designer

Step 2: Configure the middleware

Ensure that you have selected the RESPONSE tab, then select your input type, and then add the template you would like to use to the Template input box.

Setting the body response transform

Step 3: Test the Transform

If you have sample input data, you can use the Input box to add it, and then test it using the Test button. You will see the effect of the template on the sample input in the Output box.

Testing the body transform function

Step 4: Save the API

Use the save or create buttons to save the changes and activate the Response Body Transform middleware.

Configuring the middleware in Tyk Operator

The process of configuring a transformation of a response body for a specific endpoint is similar to that defined in section configuring the middleware in the Tyk Classic API Definition for the Tyk Classic API definition. To enable the middleware you must add a new transform_response object to the extended_paths section of your API definition.

In the examples below, the Response Body Transform middleware (transform_response) is directed to use the template located in the template_source, decoding the xml in the base64 encoded string. The input (pre-transformation) response payload will be xml format and there is no session metadata provided for use in the transformation.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin-transform
spec:
  name: httpbin-transform
  use_keyless: true
  protocol: http
  active: true
  proxy:
    target_url: http://httpbin.org
    listen_path: /httpbin-transform
    strip_listen_path: true
  version_data:
    default_version: Default
    not_versioned: true
    versions:
      Default:
        name: Default
        use_extended_paths: true
        paths:
          black_list: []
          ignored: []
          white_list: []
        extended_paths:
          transform:
            - method: POST
              path: /anything
              template_data:
                enable_session: false
                input_type: json
                template_mode: blob
                # base64 encoded template
                template_source: eyJiYXIiOiAie3suZm9vfX0ifQ==
          transform_headers:
            - delete_headers:
                - "remove_this"
              add_headers:
                foo: bar
              path: /anything
              method: POST
          transform_response:
            - method: GET
              path: /xml
              template_data:
                enable_session: false
                input_type: xml
                template_mode: blob
                # base64 encoded template
                template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19
          transform_response_headers:
            - method: GET
              path: /xml
              add_headers:
                Content-Type: "application/json"
              act_on: false
              delete_headers: []

Tyk Gateway < 5.3.0 Example

If using Tyk Gateway < v5.3.0 then a response_processor object must be added to the API definition containing a response_body_transform item, as highlighted below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin-transform
spec:
  name: httpbin-transform
  use_keyless: true
  protocol: http
  active: true
  proxy:
    target_url: http://httpbin.org
    listen_path: /httpbin-transform
    strip_listen_path: true
  response_processors:
    - name: response_body_transform
    - name: header_injector
  version_data:
    default_version: Default
    not_versioned: true
    versions:
      Default:
        name: Default
        use_extended_paths: true
        paths:
          black_list: []
          ignored: []
          white_list: []
        extended_paths:
          transform:
            - method: POST
              path: /anything
              template_data:
                enable_session: false
                input_type: json
                template_mode: blob
                # base64 encoded template
                template_source: eyJiYXIiOiAie3suZm9vfX0ifQ==
          transform_headers:
            - delete_headers:
                - "remove_this"
              add_headers:
                foo: bar
              path: /anything
              method: POST
          transform_response:
            - method: GET
              path: /xml
              template_data:
                enable_session: false
                input_type: xml
                template_mode: blob
                # base64 encoded template
                template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19
          transform_response_headers:
            - method: GET
              path: /xml
              add_headers:
                Content-Type: "application/json"
              act_on: false
              delete_headers: []