Use a mapping template to override an API's request and response parameters and status codes

Standard API Gateway parameter and response code mapping templates allow you to map parameters one-to-one and map a family of integration response status code, matched by a regular expression, to a single response status code. Mapping template overrides let you do the following.

• Perform many-to-one parameter mappings

• Override parameters after standard API Gateway mappings have been applied

• Conditionally map parameters based on body content or other parameter values

• Programmatically create new parameters

• Override status codes returned by your integration endpoint

Any type of request parameter, response header, or response status code may be overridden.

Use cases for overriding your API's request and response parameters and status codes

In your API, you might use a mapping template override for your API to do the following.

• To create a new header (or overwrite an existing header) as a concatenation of two parameters

• To override the response code to a success or failure code based on the contents of the body

• To conditionally remap a parameter based on its contents or the contents of some other parameter

• To iterate over the contents of a json body and remap key value pairs to headers or query strings

Considerations for overriding your API's request and response parameters and status codes

The following considerations might impact your use of mapping template overrides.

• Mapping template overrides cannot be used with proxy integration endpoints, which lack data mappings. For more information about integration types, see Choose an API Gateway API integration type.

• Overrides are final. An override may only be applied to each parameter once. If you try to override the same parameter multiple times, API Gateway returns a 5XX response. If you must override the same parameter multiple times throughout the template, we recommend creating a variable and applying the override at the end of the template. The template is applied only after the entire template is parsed. For more information, see Override an API's request parameters and headers using the AWS Management Console

Mapping template override reference

To create a mapping template override, use one or more of the following $context variables in a mapping template:

Request body mapping template	Response body mapping template
$context.requestOverride.header.header_name	$context.responseOverride.header.header_name
$context.requestOverride.path.path_name	$context.responseOverride.status
$context.requestOverride.querystring.querystring_name

For examples of overriding an API's request and response parameters and status codes, see Examples of overriding an API's request and response parameters and status codes.