Transformer-API Gateway(API Gateway)-阿里云帮助中心

The request-response rewrite plugin modifies HTTP requests before they reach your backend and HTTP responses before they reach the client. Use it to add, overwrite, or remove request parameters (Header, Query, and Form) and response headers, and to override the response status code.

Supported operations

The plugin intercepts traffic at two points in the request lifecycle: after parameter mapping on the inbound path, and after error code mapping on the outbound path. At each point, it applies the transformation rules you configure.

The following operations are supported for HTTP requests:

addRequestParameterIfAbsent: Adds a parameter at the specified location (Header, Query, or Form) with the given name and value. If the parameter already exists, it is left unchanged.
putRequestParameter: Adds a parameter at the specified location with the given name and value. If the parameter already exists, its value is overwritten.
removeRequestParameter: Removes a parameter from the specified location. Provide the location and parameter name.

The following operations are supported for HTTP responses:

setResponseStatusCode: Overrides the status code returned by the backend service.
addResponseHeaderIfAbsent: Adds a response header with the given name and value. If the header already exists, it is left unchanged.
putResponseHeader: Adds a response header with the given name and value. If the header already exists, its value is overwritten.
removeResponseHeader: Removes a response header by name.

Note

Request operations support three parameter locations: Header, Query, and Form. Response operations only support Header.

Important

Request transformations run after parameter mapping, before the request is forwarded to the backend. Response transformations run after error code mapping, before the response is returned to the client.

Configuration example

Configure the plugin in YAML or JSON — both use the same schema. Use a YAML-to-JSON conversion tool to switch between formats. The following YAML template covers all supported operations:

---
addRequestParameterIfAbsent:         # Add to request; skip if the parameter already exists.
  - name: userId
    value: 123456
    location: query
putRequestParameter:                 # Add to request; overwrite if the parameter already exists.
  - name: name
    value: Jack
    location: header
removeRequestParameter:              # Remove from request.
  - name: address
    location: form
setResponseStatusCode: 200           # Override the response status code.
addResponseHeaderIfAbsent:           # Add to response header; skip if the header already exists.
  - name: age
    value: 18
putResponseHeader:                   # Add to response header; overwrite if the header already exists.
  - name: name
    value: Alice
removeResponseHeader:                # Remove from response header.
  - name: phone

The key distinction between addRequestParameterIfAbsent / addResponseHeaderIfAbsent and putRequestParameter / putResponseHeader is what happens when the parameter already exists:

addRequestParameterIfAbsent: API Gateway checks whether userId is present in the query string before forwarding the request. If it is missing, API Gateway injects it with the value 123456. If it already exists, API Gateway leaves it unchanged — useful for setting defaults without clobbering values the client already sent.
putResponseHeader: API Gateway sets the name response header to Alice regardless of whether the header is already present. If the header exists, its value is overwritten — useful for enforcing a specific header value on every response.

Limits

The request-response rewrite plugin is available only on dedicated instances.

For dedicated instances purchased before April 2, 2024: if a configuration fails to apply, submit a ticket to upgrade the instance version.