Understanding mapping templates

In API Gateway, an API's method request or response can take a payload in a different format from the integration request or response.

You can transform your data to:

• Match the payload to an API-specified format.

• Override an API's request and response parameters and status codes.

• Return client selected response headers.

• Associate path parameters, query string parameters, or header parameters in the method request of HTTP proxy or AWS service proxy.

• Select which data to send using integration with AWS services, such as Amazon DynamoDB or Lambda functions, or HTTP endpoints.

You can use mapping templates to transform your data. A mapping template is a script expressed in Velocity Template Language (VTL) and applied to the payload using JSONPath .

The following example shows input data, a mapping template, and output data for a transformation of the PetStore data.

Input data	[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
Mapping template	#set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ]
Output data	[ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ]

The following diagram shows details of this mapping template.

1. The $inputRoot variable represents the root object in the original JSON data from the previous section. Directives begin with the # symbol.

2. A foreach loop iterates though each object in the original JSON data.

3. The description is a concatenation of the Pet's id and type from the original JSON data.

4. askingPrice is the price is the price from the original JSON data.

PetStore mapping template

1 #set($inputRoot = $input.path('$'))
2 [
3 #foreach($elem in $inputRoot)
4  {
5    "description" : "Item $elem.id is a $elem.type.",
6    "askingPrice" : $elem.price
7  }#if($foreach.hasNext),#end
8 #end
9 ]

In this mapping template:

1. On line 1, the $inputRoot variable represents the root object in the original JSON data from the previous section. Directives begin with the # symbol.

2. On line 3, a foreach loop iterates through each object in the original JSON data.

3. On line 5, the description is a concatenation of the Pet's id and type from the original JSON data.

4. On line 6, askingPrice is the price is the price from the original JSON data.

For more information about the Velocity Template Language, see Apache Velocity - VTL Reference. For more information about JSONPath, see JSONPath - XPath for JSON.

The mapping template assumes that the underlying data is of a JSON object. It does not require that a model be defined for the data. However, a model for the output data allows preceding data to be returned as a language-specific object. For more information, see Understanding data models.

Complex mapping templates

You can also create more complicated mapping templates. The following example shows the concatenation of references and a cutoff of 100 to determine if a pet is affordable.

Input data	[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
Mapping template	#set($inputRoot = $input.path('$')) #set($cheap = 100) [ #foreach($elem in $inputRoot) { #set($name = "${elem.type}number$elem.id") "name" : $name, "description" : "Item $elem.id is a $elem.type.", #if($elem.price > $cheap )#set ($afford = 'too much!') #{else}#set ($afford = $elem.price)#end "askingPrice" : $afford }#if($foreach.hasNext),#end #end ]
Output data	[ { "name" : dognumber1, "description" : "Item 1 is a dog.", "askingPrice" : too much! }, { "name" : catnumber2, "description" : "Item 2 is a cat.", "askingPrice" : too much! }, { "name" : fishnumber3, "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ]

See the example photo album Photos example for a more complicated model.