Amazon API Gateway
Developer Guide

API Gateway Mapping Template and Access Logging Variable Reference

This section provides reference information for the variables and functions that Amazon API Gateway defines for use with data models, authorizers, mapping templates, and CloudWatch access logging. For detailed information about how to use these variables and functions, see Create Models and Mapping Templates for Request and Response Mappings.

Note

For $method and $integration variables, see Amazon API Gateway API Request and Response Data Mapping Reference.

$context Variables for Data Models, Authorizers, Mapping Templates, and CloudWatch Access Logging

The following $context variables can be used in data models, authorizers, mapping templates, and CloudWatch access logging.

For $context variables that can be used only in CloudWatch access logging, see $context Variables for CloudWatch Access Logging Only.

Parameter Description
$context.accountId

The API owner's AWS account ID.

$context.apiId

The identifier API Gateway assigns to your API.

$context.authorizer.claims.property

A property of the claims returned from the Amazon Cognito user pool after the method caller is successfully authenticated. For more information, see Control Access to a REST API Using Amazon Cognito User Pools as Authorizer.

Note

Calling $context.authorizer.claims returns null.

$context.authorizer.principalId

The principal user identification associated with the token sent by the client and returned from an API Gateway Lambda authorizer (formerly known as a custom authorizer). For more information, see Use API Gateway Lambda Authorizers.

$context.authorizer.property

The stringified value of the specified key-value pair of the context map returned from an API Gateway Lambda authorizer function. For example, if the authorizer returns the following context map:

"context" : { "key": "value", "numKey": 1, "boolKey": true }

calling $context.authorizer.key returns the "value" string, calling $context.authorizer.numKey returns the "1" string, and calling $context.authorizer.boolKey returns the "true" string.

For more information, see Use API Gateway Lambda Authorizers.

$context.awsEndpointRequestId

The AWS endpoint's request ID.

$context.domainName

The full domain name used to invoke the API. This should be the same as the incoming Host header.

$context.domainPrefix

The first label of the $context.domainName. This is often used as a caller/customer identifier.

$context.error.message

A string containing an API Gateway error message. This variable can only be used for simple variable substitution in a GatewayResponse body-mapping template, which is not processed by the Velocity Template Language engine, and in access logging. For more information, see Monitor WebSocket API Execution with CloudWatch and Set up Gateway Responses to Customize Error Responses.

$context.error.messageString The quoted value of $context.error.message, namely "$context.error.message".
$context.error.responseType

A type of GatewayResponse. This variable can only be used for simple variable substitution in a GatewayResponse body-mapping template, which is not processed by the Velocity Template Language engine, and in access logging. For more information, see Monitor WebSocket API Execution with CloudWatch and Set up Gateway Responses to Customize Error Responses.

$context.error.validationErrorString

A string containing a detailed validation error message.

$context.extendedRequestId The extended ID that API Gateway assigns to the API request, which contains more useful information for debugging/troubleshooting.
$context.httpMethod

The HTTP method used. Valid values include: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT.

$context.identity.accountId

The AWS account ID associated with the request.

$context.identity.apiKey

For API methods that require an API key, this variable is the API key associated with the method request. For methods that don't require an API key, this variable is null. For more information, see Create and Use Usage Plans with API Keys.

$context.identity.apiKeyId The API key ID associated with an API request that requires an API key.
$context.identity.caller

The principal identifier of the caller making the request.

$context.identity.cognitoAuthenticationProvider

The Amazon Cognito authentication provider used by the caller making the request. Available only if the request was signed with Amazon Cognito credentials. For information, see Using Federated Identities in the Amazon Cognito Developer Guide.

$context.identity.cognitoAuthenticationType

The Amazon Cognito authentication type of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

$context.identity.cognitoIdentityId

The Amazon Cognito identity ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

$context.identity.cognitoIdentityPoolId

The Amazon Cognito identity pool ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

$context.identity.principalOrgId

The AWS organization ID.

$context.identity.sourceIp

The source IP address of the TCP connection making the request to API Gateway.

Warning

You should not trust this value if there is any chance that the X-Forwarded-For header could be forged.

$context.identity.user

The principal identifier of the user making the request. Used in Lambda authorizers. For more information, see Output from an Amazon API Gateway Lambda Authorizer.

$context.identity.userAgent

The User-Agent header of the API caller.

$context.identity.userArn

The Amazon Resource Name (ARN) of the effective user identified after authentication. For more information, see https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.

$context.path The request path. For example, for a non-proxy request URL of https://{rest-api-id.execute-api.{region}.amazonaws.com/{stage}/root/child, the $context.path value is /{stage}/root/child.
$context.protocol The request protocol, for example, HTTP/1.1.
$context.requestId

The ID that API Gateway assigns to the API request.

$context.requestOverride.header.header_name

The request header override. If this parameter is defined, it contains the headers to be used instead of the HTTP Headers that are defined in the Integration Request pane. For more information, see Use a Mapping Template to Override an API's Request and Response Parameters and Status Codes.

$context.requestOverride.path.path_name

The request path override. If this parameter is defined, it contains the request path to be used instead of the URL Path Parameters that are defined in the Integration Request pane. For more information, see Use a Mapping Template to Override an API's Request and Response Parameters and Status Codes.

$context.requestOverride.querystring.querystring_name

The request query string override. If this parameter is defined, it contains the request query strings to be used instead of the URL Query String Parameters that are defined in the Integration Request pane. For more information, see Use a Mapping Template to Override an API's Request and Response Parameters and Status Codes.

$context.responseOverride.header.header_name The response header override. If this parameter is defined, it contains the header to be returned instead of the Response header that is defined as the Default mapping in the Integration Response pane. For more information, see Use a Mapping Template to Override an API's Request and Response Parameters and Status Codes.
$context.responseOverride.status The response status code override. If this parameter is defined, it contains the status code to be returned instead of the Method response status that is defined as the Default mapping in the Integration Response pane. For more information, see Use a Mapping Template to Override an API's Request and Response Parameters and Status Codes.
$context.requestTime The CLF-formatted request time (dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch The Epoch-formatted request time.
$context.resourceId

The identifier that API Gateway assigns to your resource.

$context.resourcePath

The path to your resource. For example, for the non-proxy request URI of https://{rest-api-id.execute-api.{region}.amazonaws.com/{stage}/root/child, The $context.resourcePath value is /root/child. For more information, see TUTORIAL: Build an API with HTTP Non-Proxy Integration.

$context.stage

The deployment stage of the API request (for example, Beta or Prod).

$context.wafResponseCode

The response received from AWS WAF: WAF_ALLOW or WAF_BLOCK. Will not be set if the stage is not associated with a web ACL. For more information, see Use AWS WAF to Protect Your Amazon API Gateway API from Common Web Exploits.

$context.webaclArn

The complete ARN of the web ACL that is used to decide whether to allow or block the request. Will not be set if the stage is not associated with a web ACL. For more information, see Use AWS WAF to Protect Your Amazon API Gateway API from Common Web Exploits.

$context.xrayTraceId

The trace ID for the X-Ray trace. For more information, see Setting Up AWS X-Ray with API Gateway.

$context Variable Template Example

You may want to use $context variables in a mapping template if your API method passes structured data to a backend that requires the data to be in a particular format.

The following example shows a mapping template that maps incoming $context variables to backend variables with slightly different names in an integration request payload:

Note

Note that one of the variables is an API key. This example assumes that the method has "require API key" enabled.

{ "stage" : "$context.stage", "request_id" : "$context.requestId", "api_id" : "$context.apiId", "resource_path" : "$context.resourcePath", "resource_id" : "$context.resourceId", "http_method" : "$context.httpMethod", "source_ip" : "$context.identity.sourceIp", "user-agent" : "$context.identity.userAgent", "account_id" : "$context.identity.accountId", "api_key" : "$context.identity.apiKey", "caller" : "$context.identity.caller", "user" : "$context.identity.user", "user_arn" : "$context.identity.userArn" }

$context Variables for CloudWatch Access Logging Only

The following $context variables are available only for CloudWatch access logging. For more information, see Set Up CloudWatch API Logging in API Gateway. (For WebSocket APIs, see Monitor WebSocket API Execution with CloudWatch.)

Parameter Description
$context.authorizer.integrationLatency The authorizer latency in ms.
$context.integrationLatency The integration latency in ms.
$context.integrationStatus For Lambda proxy integration, this parameter represents the status code returned from AWS Lambda, not from the backend Lambda function.
$context.responseLatency The response latency in ms.
$context.responseLength The response payload length.
$context.status The method response status.

$input Variables

The $input variable represents the method request payload and parameters to be processed by a mapping template. It provides four functions:

Variable and Function Description
$input.body

Returns the raw request payload as a string.

$input.json(x)

This function evaluates a JSONPath expression and returns the results as a JSON string.

For example, $input.json('$.pets') returns a JSON string representing the pets structure.

For more information about JSONPath, see JSONPath or JSONPath for Java.

$input.params()

Returns a map of all the request parameters.

$input.params(x)

Returns the value of a method request parameter from the path, query string, or header value (searched in that order), given a parameter name string x.

$input.path(x)

Takes a JSONPath expression string (x) and returns a JSON object representation of the result. This allows you to access and manipulate elements of the payload natively in Apache Velocity Template Language (VTL).

For example, if the expression $input.path('$.pets') returns an object like this:

[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]

$input.path('$.pets').count() would return "3".

For more information about JSONPath, see JSONPath or JSONPath for Java.

$input Variable Template Examples

Parameter Mapping Template Example

The following parameter-mapping example passes all parameters, including path, querystring, and header, through to the integration endpoint via a JSON payload:

#set($allParams = $input.params()) { "params" : { #foreach($type in $allParams.keySet()) #set($params = $allParams.get($type)) "$type" : { #foreach($paramName in $params.keySet()) "$paramName" : "$util.escapeJavaScript($params.get($paramName))" #if($foreach.hasNext),#end #end } #if($foreach.hasNext),#end #end } }

In effect, this mapping template outputs all the request parameters in the payload as outlined as follows:

{ "parameters" : { "path" : { "path_name" : "path_value", ... } "header" : { "header_name" : "header_value", ... } "querystring" : { "querystring_name" : "querystring_value", ... } } }

You may want to use the $input variable to get query strings and the request body with or without using models. You may also want to get the parameter and the payload, or a subsection of the payload, into your Lambda function. The following examples show how to do this.

Example JSON Mapping Template Using $input

The following example shows how to use a mapping to read a name from the query string and then include the entire POST body in an element:

{ "name" : "$input.params('name')", "body" : $input.json('$') }

If the JSON input contains unescaped characters that cannot be parsed by JavaScript, a 400 response may be returned. Applying $util.escapeJavaScript($input.json('$')) above will ensure that the JSON input can be parsed properly.

Example Mapping Template Using $input

The following example shows how to pass a JSONPath expression to the json() method. You could also read a specific property of your request body object by using a period (.), followed by your property name:

{ "name" : "$input.params('name')", "body" : $input.json('$.mykey') }

If a method request payload contains unescaped characters that cannot be parsed by JavaScript, you may get 400 response. In this case, you need to call $util.escapeJavaScript() function in the mapping template, as shown as follows:

{ "name" : "$input.params('name')", "body" : $util.escapeJavaScript($input.json('$.mykey')) }

Example Request and Response Using $input

Here's an example that uses all three functions:

Request Template:

Resource: /things/{id} With input template: { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : $util.escapeJavaScript($input.json('$.things')) } POST /things/abc { "things" : { "1" : {}, "2" : {}, "3" : {} } }

Response:

{ "id": "abc", "count": "3", "things": { "1": {}, "2": {}, "3": {} } }

For more mapping examples, see Create Models and Mapping Templates for Request and Response Mappings.

$stageVariables

Stage variables can be used in parameter mapping and mapping templates and as placeholders in ARNs and URLs used in method integrations. For more information, see Set up Stage Variables for a REST API Deployment.

Syntax Description
$stageVariables.<variable_name>

<variable_name> represents a stage variable name.

$stageVariables['<variable_name>']

<variable_name> represents any stage variable name.

${stageVariables['<variable_name>']}

<variable_name> represents any stage variable name.

$util Variables

The $util variable contains utility functions for use in mapping templates.

Note

Unless otherwise specified, the default character set is UTF-8.

Function Description
$util.escapeJavaScript()

Escapes the characters in a string using JavaScript string rules.

Note

This function will turn any regular single quotes (') into escaped ones (\'). However, the escaped single quotes are not valid in JSON. Thus, when the output from this function is used in a JSON property, you must turn any escaped single quotes (\') back to regular single quotes ('). This is shown in the following example:

$util.escapeJavaScript(data).replaceAll("\\'","'")
$util.parseJson()

Takes "stringified" JSON and returns an object representation of the result. You can use the result from this function to access and manipulate elements of the payload natively in Apache Velocity Template Language (VTL). For example, if you have the following payload:

{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}

and use the following mapping template

#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage'))) { "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0] }

You will get the following output:

{ "errorMessageObjKey2ArrVal" : 1 }
$util.urlEncode()

Converts a string into "application/x-www-form-urlencoded" format.

$util.urlDecode()

Decodes an "application/x-www-form-urlencoded" string.

$util.base64Encode()

Encodes the data into a base64-encoded string.

$util.base64Decode()

Decodes the data from a base64-encoded string.