# Transform API requests and responses for HTTP APIs in API Gateway
<a name="http-api-parameter-mapping"></a>

You can modify API requests from clients before they reach your backend integrations. You can also change the response from integrations before API Gateway returns the response to clients. You use *parameter mapping* to modify API requests and responses for HTTP APIs. To use parameter mapping, you specify API request or response parameters to modify, and specify how to modify those parameters.



## Transforming API requests
<a name="http-api-mapping-request-parameters"></a>

You use request parameters to change requests before they reach your backend integrations. You can modify headers, query strings, or the request path.

Request parameters are a key-value map. The key identifies the location of the request parameter to change, and how to change it. The value specifies the new data for the parameter.

The following table shows supported keys.


| Type | Syntax | 
| --- | --- | 
| Header | append\$1overwrite\$1remove:header.headername | 
| Query string | append\$1overwrite\$1remove:querystring.querystring-name | 
| Path | overwrite:path | 

The following table shows supported values that you can map to parameters.


| Type | Syntax | Notes | 
| --- | --- | --- | 
| Header value | \$1request.header.name or \$1\$1request.header.name\$1 | Header names are case-insensitive. API Gateway combines multiple header values with commas, for example "header1": "value1,value2". Some headers are reserved. To learn more, see [Reserved headers](#http-api-mapping-reserved-headers). | 
| Query string value | \$1request.querystring.name or \$1\$1request.querystring.name\$1 | Query string names are case-sensitive. API Gateway combines multiple values with commas, for example "querystring1" "Value1,Value2". | 
| Request body | \$1request.body.name or \$1\$1request.body.name\$1 | A JSON path expression. Recursive descent (\$1request.body..name) and filter expressions (?(expression)) aren't supported.  When you specify a JSON path, API Gateway truncates the request body at 100 KB and then applies the selection expression. To send payloads larger than 100 KB, specify `$request.body`.   | 
| Request path | \$1request.path or \$1\$1request.path\$1 | The request path, without the stage name. | 
| Path parameter | \$1request.path.name or \$1\$1request.path.name\$1 | The value of a path parameter in the request. For example if the route is /pets/\$1petId\$1, you can map the petId parameter from the request with \$1request.path.petId. | 
| Context variable | \$1context.variableName or \$1\$1context.variableName\$1 | The value of a [context variable](http-api-logging-variables.md). Only the special characters `.` and `_` are supported. | 
| Stage variable | \$1stageVariables.variableName or \$1\$1stageVariables.variableName\$1 | The value of a [stage variable](http-api-stages.stage-variables.md). | 
| Static value | string | A constant value. | 

**Note**  
To use multiple variables in a selection expression, enclose the variable in brackets. For example, `${request.path.name} ${request.path.id}`.

## Transforming API responses
<a name="http-api-mapping-response-parameters"></a>

You use response parameters to transform the HTTP response from a backend integration before returning the response to clients. You can modify headers or the status code of a response before API Gateway returns the response to clients.

You configure response parameters for each status code that your integration returns. Response parameters are a key-value map. The key identifies the location of the request parameter to change, and how to change it. The value specifies the new data for the parameter.

The following table shows supported keys.


| Type | Syntax | 
| --- | --- | 
| Header | append\$1overwrite\$1remove:header.headername | 
| Status code | overwrite:statuscode | 

The following table shows supported values that you can map to parameters.


| Type | Syntax | Notes | 
| --- | --- | --- | 
| Header value | \$1response.header.name or \$1\$1response.header.name\$1 | Header names are case-insensitive. API Gateway combines multiple header values with commas, for example "header1": "value1,value2". Some headers are reserved. To learn more, see [Reserved headers](#http-api-mapping-reserved-headers). | 
| Response body | \$1response.body.name or \$1\$1response.body.name\$1 | A JSON path expression. Recursive descent (\$1response.body..name) and filter expressions (?(expression)) aren't supported.  When you specify a JSON path, API Gateway truncates the response body at 100 KB and then applies the selection expression. To send payloads larger than 100 KB, specify `$response.body`.   | 
| Context variable | \$1context.variableName or \$1\$1context.variableName\$1 | The value of a supported [context variable](http-api-logging-variables.md). | 
| Stage variable | \$1stageVariables.variableName or \$1\$1stageVariables.variableName\$1 | The value of a [stage variable](http-api-stages.stage-variables.md). | 
| Static value | string | A constant value. | 

**Note**  
To use multiple variables in a selection expression, enclose the variable in brackets. For example, `${request.path.name} ${request.path.id}`.

## Reserved headers
<a name="http-api-mapping-reserved-headers"></a>

The following headers are reserved. You can't configure request or response mappings for these headers.
+ access-control-\$1
+ apigw-\$1
+ Authorization
+ Connection
+ Content-Encoding
+ Content-Length
+ Content-Location
+ Forwarded
+ Keep-Alive
+ Origin
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers 
+ Transfer-Encoding
+ Upgrade
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via

## Examples
<a name="http-api-parameter-mapping-examples"></a>

The following AWS CLI examples configure parameter mappings. For example CloudFormation templates, see [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).

### Add a header to an API request
<a name="http-api-parameter-mapping-examples-request-header"></a>

The following [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) command creates a header named `header1` to an API request before it reaches your backend integration. API Gateway populates the header with the request ID.

```
aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }'
```

### Rename a request header
<a name="http-api-parameter-mapping-examples-response"></a>

The following [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) command renames a request header from `header1` to `header2`:

```
aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'
```

### Change the response from an integration
<a name="http-api-parameter-mapping-examples-response"></a>

The following [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) command configures response parameters for an integration. When the integrations returns a 500 status code, API Gateway changes the status code to 403, and adds `header1`1 to the response. When the integration returns a 404 status code, API Gateway adds an `error` header to the response.

```
aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'
```

### Remove configured parameter mappings
<a name="http-api-parameter-mapping-examples-remove"></a>

The following [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) command removes previously configured request parameters for `append:header.header1`. It also removes previously configured response parameters for a 200 status code.

```
aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'
```