How do I transform a request and its response using Transformation Policy?

Edit online

About this task

Use the Response Transformation policy to modify the contents of an outgoing response such as headers, payload, query parameters, path parameters, HTTP method using the configurations given by the API Provider.

The response transformation workflow is as follows:

  1. The API Provider configures the Response Transformation policy in the Response Processing stage of API Gateway. The API provider configures the details about when and how to transform contents of an outgoing response.
  2. The client sends the request to API Gateway.
  3. API Gateway forwards the request to native API.
  4. Native API processes the request and sends response to API Gateway.
  5. API Gateway applies the transformations configured by the API Provider and transforms the outgoing response.
  6. API Gateway forwards the transformed response to the client.

Consider a scenario, where a native API URL is moved permanently or temporarily, the native API sends a 301 or 302 status code, and also sends the new address in the location header. However, when API Gateway comes across the 301 or 302 status code, API Gateway reads the status code and the location header, and redirects the request to new address mentioned in the location header. API Gateway, then sends the response from the new address to the client. This is how 3xx status code is handled in API Gateway.

In this scenario, if you do not want API Gateway to do the redirection, instead you want the clients to receive the 3xx status code, and then do the redirection. This can be achieved by using the Status Transformation policy in the Response Processing stage.

To achieve this transformation:

Procedure

  1. Change the native API to send an intermediate 2xx status code instead of 3xx status code, for request from API Gateway.

    For example, a demo service package contains a couple of REST services - source and destination.

    The REST service source is moved to a new address and it sends a 301 status along with location header. However, it sends 297 status code with the location header for requests from API Gateway. The location header contains the address for destination, which is the new address of the moved resource.

  2. Configure the API in API Gateway with a Request Transformation policy to send a request header requestOrigin with the value APIGateway. To configure the request transformation policy, perform the following steps:
    1. Click APIs in the title navigation bar.
      A list of available APIs appears.
    2. Select a Rest API from the list of APIs and click Edit.
    3. Select Policies > Request Processing > Request Transformation.
      The Request Transformation details page appears.
    4. In the Condition section, select OR.

      The configured transformation is applied when at least one of the conditions is satisfied.

      Note: The condition can also be set to AND operator. The configured transformation is applied only when all the set conditions are satisfied.
    5. Click Add Condition to configure the conditions to evaluate the contents on the request.
    6. Specify the Variable. Example, Content-Type.
    7. Specify the Operator to use to relate variable and the value provided. Example, Equals.
    8. Specify the Value. Example, application/json.

      When you select the operator - Equals, the Condition checks if the Variable: Content-Type is equal to the Value: application/json.

    9. Click Add.
    10. Select Transformation Configuration > Header/Query/Path transformation.
      The Header/Query/Path transformation details page appears.
    11. In Add/Modify section, add the variable and set its value.

      Set the Variable and Value parameters as follows:

      • Variable: ${request.headers.requestOrigin}
      • Value: APIGateway
      Note: For details about the variables available in API Gateway, see Variables Available in API Gateway.
    12. Click Save.
    This Request Transformation policy allows the API in API Gateway to send a request header requestOrigin with the value APIGateway. This will help the native API identify the request from API Gateway and send the response code 297.
  3. Configure the API in API Gateway with the Status Transformation policy to transform the 297 status code to 301 status code. To configure the status transformation policy, perform the following steps:
    1. Click APIs in the title navigation bar.
      A list of available APIs appears.
    2. Select a Rest API from the list of APIs and click Edit.
    3. Select Policies > Response Processing > Response Transformation .
      The Response Transformation details page appears.
    4. In the Condition section, select OR.

      The configured transformation is applied when at least one of the conditions is satisfied.

      Note: The condition can also be set to AND operator. The configured transformation is applied only when all the set conditions are satisfied.
    5. Click Add Condition to configure the conditions to evaluate the contents on the request.
    6. Specify the Variable. Example, ${response.statusCode}.
      Note: For details about the variables available in API Gateway, see Variables Available in API Gateway.
    7. Specify the Operator to use to relate variable and the value provided. Example, Equals.
    8. Specify the Value. Example, 297.

      When you select the operator - Equals, the Condition checks if the Variable: ${response.statusCode} is equal to the Value: 297.

    9. Click Add.
    10. Select Transformation Configuration > Status transformation.
      The Status transformation details page appears.
    11. Specify the Code and Message values that you would like in the response.

      Set the Code and Message parameters as follows:

      • Code: 301
      • Message: Moved Permanently
    12. Click Save.

Results

This transformation policy allows the clients to receive the 301 status code, and then redirect to the new address mentioned in location header.