Transformer - API Gateway - Alibaba Cloud Documentation Center

Transformer plug-ins automatically apply the changes that you want to make to HTTP requests and responses, such as the parameters in the Header, Query, and Form sections of requests and the status codes and Header parameters in responses.

1. Overview

Transformer plug-ins allow you to configure parameter modification policies, such as the modification types and parameters to be modified. Then, the plug-ins automatically modify HTTP requests and responses based on the configured policies.

The following modification types are supported for HTTP requests:

addRequestParameterIfAbsent: Add request parameters. If a parameter already exists, the parameter is not modified. You must provide the location, name, and value of the parameter that you want to add.
putRequestParameter: Add request parameters. If a parameter already exists, the new parameter overwrites the original. You must provide the location, name, and value of the parameter that you want to add.
removeRequestParameter: Delete request parameters. You must provide the location and name of the parameter that you want to delete.

The following modification types are supported for HTTP responses:

setResponseStatusCode: Set the status code of the response. This status code overwrites the status code returned by the backend service.
addResponseHeaderIfAbsent: Add parameters to the header. If a parameter already exists, the parameter is not modified. You must provide the parameter name and value.
putResponseHeader: Add parameters to the header. If a parameter already exists, the new parameter overwrites the original. You must provide the parameter name and value.
removeResponseHeader: Delete parameters from the header. You must provide the parameter name.

Note

You can specify Header, Query, or Form as the location of a parameter that you want to add or delete for a request.

Important

Before forwarding a request to the backend service, API Gateway executes the policy configured in a transformer plug-in to modify the parameters in the request. If request parameters need to be mapped, the policy is applied after parameter mapping. Before forwarding a response to the client, API Gateway executes the policy configured in a transformer plug-in to modify the parameters in the response. If the error code needs to be mapped, the policy is applied after error code mapping.

2. Configuration example

You can configure a transformer plug-in in JSON or YAML format. The two formats have the same schema and can be converted to each other by using a conversion tool. The following code provides a template in YAML format:

---
addRequestParameterIfAbsent:         # Add parameters to the request. If a parameter already exists, the parameter is not modified.
  - name: userId                     # The parameter name.
    value: 123456                    # The parameter value.
    location: query                  # The parameter location.
putRequestParameter:                 # Add parameters to the request. If a parameter already exists, the new parameter overwrites the original.
  - name: name
    value: Jack
    location: header
removeRequestParameter:              # Delete parameters from the request.
  - name: address
    location: form
setResponseStatusCode: 200           # Set a status code for the response.
addResponseHeaderIfAbsent:           # Add parameters to the header. If a parameter already exists, the parameter is not modified.
  - name: age
    value: 18
putResponseHeader:                   # Add parameters to the header. If a parameter already exists, the new parameter overwrites the original.
  - name: name
    value: Alice
removeResponseHeader: # Delete parameters from the header.
  - name: phone

Take addRequestParameterIfAbsent and putResponseHeader for examples:

addRequestParameterIfAbsent: If the request does not contain the userId parameter in the Query section, API Gateway adds the parameter and sets its value to 123456. If the request contains the userId parameter, API Gateway does not modify the parameter.
putResponseHeader: API Gateway adds the age parameter and sets its value to 18 to the header of the response, regardless of whether the header already contains the parameter, in which case API Gateway changes the parameter value to 18.

3. Limits

Transformer plug-ins are provided only for dedicated instances.

If transformer plug-ins do not take effect in your dedicated instance that was purchased before April 02, 2024, submit a ticket to have your instance upgraded.