Variables for data transformations for API Gateway

Focus mode

Variables for data transformations for API Gateway - Amazon API Gateway

Context variables for data transformations Input variables Stage variables Util variables

When you create a parameter mapping, you can use context variables as your data source. When you create mapping template transformations, you can use context variables, input, and util variables in scripts you write in Velocity Template Language (VTL). For example mapping templates that use these reference variables, see Examples using variables for mapping template transformations for API Gateway.

For a list of reference variables for access logging, see Variables for access logging for API Gateway.

Context variables for data transformations

You can use the following $context variables for data transformations.

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 REST APIs using Amazon Cognito user pools as an 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 `property`, the only supported special character is the underscore `(_)` character. For more information, see Use API Gateway Lambda authorizers.
`$context.awsEndpointRequestId`	The AWS endpoint's request ID.
`$context.deploymentId`	The ID of the API deployment.
`$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`.
`$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 metrics and Setting 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 metrics and Setting 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 generates and assigns to the API request. The extended request ID contains useful information for debugging and 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 Usage plans and API keys for REST APIs in API Gateway.
`$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 that signed the request. Supported for resources that use IAM authorization.
`$context.identity.cognitoAuthenticationProvider`	A comma-separated list of all the Amazon Cognito authentication providers used by the caller making the request. Available only if the request was signed with Amazon Cognito credentials. For example, for an identity from an Amazon Cognito user pool, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` For information about the available Amazon Cognito authentication providers, 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. Possible values include `authenticated` for authenticated identities and `unauthenticated` for unauthenticated identities.
`$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 immediate TCP connection making the request to the API Gateway endpoint.
`$context.identity.clientCert.clientCertPem`	The PEM-encoded client certificate that the client presented during mutual TLS authentication. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
`$context.identity.clientCert.subjectDN`	The distinguished name of the subject of the certificate that a client presents. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
`$context.identity.clientCert.issuerDN`	The distinguished name of the issuer of the certificate that a client presents. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
`$context.identity.clientCert.serialNumber`	The serial number of the certificate. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
`$context.identity.clientCert.validity.notBefore`	The date before which the certificate is invalid. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
`$context.identity.clientCert.validity.notAfter`	The date after which the certificate is invalid. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
`$context.identity.vpcId`	The VPC ID of the VPC making the request to the API Gateway endpoint.
`$context.identity.vpceId`	The VPC endpoint ID of the VPC endpoint making the request to the API Gateway endpoint. Present only when you have a private API.
`$context.identity.user`	The principal identifier of the user that will be authorized against resource access. Supported for resources that use IAM authorization.
`$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.isCanaryRequest`	Returns `true` if the request was directed to the canary and `false` if the request was not directed to the canary. Present only when you have a canary enabled.
`$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`. Note API Gateway APIs can accept HTTP/2 requests, but API Gateway sends requests to backend integrations using HTTP/1.1. As a result, the request protocol is logged as HTTP/1.1 even if a client sends a request that uses HTTP/2.
`$context.requestId`	An ID for the request. Clients can override this request ID. Use `$context.extendedRequestId` for a unique request ID that API Gateway generates.
`$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 Override your API's request and response parameters and status codes for REST APIs in API Gateway.
`$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 Override your API's request and response parameters and status codes for REST APIs in API Gateway.
`$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 Override your API's request and response parameters and status codes for REST APIs in API Gateway.
`$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 Override your API's request and response parameters and status codes for REST APIs in API Gateway.
`$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 Override your API's request and response parameters and status codes for REST APIs in API Gateway.
`$context.requestTime`	The CLF-formatted request time (`dd/MMM/yyyy:HH:mm:ss +-hhmm`).
`$context.requestTimeEpoch`	The Epoch-formatted request time, in milliseconds.
`$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: Create a REST API with an 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 REST APIs in API Gateway.
`$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 REST APIs in API Gateway.

Input variables

You can use the following $input variables to refer to the method request payload and method request parameters. The following functions are available:

Variable and function	Description
`$input.body`	Returns the raw request payload as a string. You can use `$input.body` to preserve entire floating point numbers, such as `10.00`.
`$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. We recommend that you use `$util.escapeJavaScript` to sanitize the result to avoid a potential injection attack. For full control of request sanitization, use a proxy integration without a template and handle request sanitization in your integration.
`$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`. We recommend that you use `$util.escapeJavaScript` to sanitize the parameter to avoid a potential injection attack. For full control of parameter sanitization, use a proxy integration without a template and handle request sanitization in your integration.
`$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').size()` would return `"3"`. For more information about JSONPath, see JSONPath or JSONPath for Java.

Stage variables

You can use the following stage variables as placeholders for ARNs and URLs in method integrations. For more information, see Use stage variables for a REST API in API Gateway.

Syntax	Description
`$stageVariables.variable_name`, `$stageVariables['variable_name']`, or `${stageVariables['variable_name']}`	`variable_name` represents a stage variable name.

Util variables

You can use the following $util variables to use utility functions for mapping templates. 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: `"input" : "$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.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Examples using variables for mapping template transformations

Gateway responses

Select your cookie preferences

Customize cookie preferences

Essential

Performance

Functional

Advertising

Unable to save cookie preferences

Variables for data transformations for API Gateway

Context variables for data transformations

Note

Note

Input variables

Stage variables

Util variables

Note

On this page

Related resources

Did this page help you?

Related resources

Next topic:

Previous topic:

Need help?