Menu
Amazon API Gateway
Developer Guide

Amazon API Gateway API Request and Response Data Mapping

This section explains how to set up data mappings from an API's method request data, including other data stored in context, stage or util variables, to the corresponding integration request parameters and from an integration response data, including the other data, to the method response parameters. The method request data includes request parameters (path, query string, headers) and the body The integration response data includes response parameters (headers), and the body. For more information about using the stage variables, see Amazon API Gateway Stage Variables Reference.

Map Data to Integration Request Parameters

Integration request parameters, in the form of path variables, query strings or headers, can be mapped from any defined method request parameters and the payload.

Integration request data mapping expressions

Mapped data source Mapping expression
Method request path method.request.path.PARAM_NAME
Method request query string method.request.querystring.PARAM_NAME
Method request header method.request.header.PARAM_NAME
Method request body method.request.body
Method request body (JsonPath) method.request.body.JSONPath_EXPRESSION.
Stage variables stageVariables.VARIABLE_NAME
Context variables context.VARIABLE_NAME that must be one of the supported context variables.
Static value 'STATIC_VALUE'. The STATIC_VALUE is a string literal and must be enclosed within a pair of single quotes.

Here, PARAM_NAME is the name of a method request parameter of the given parameter type. It must have been defined before it can be referenced. JSONPath_EXPRESSION is a JSONPath expression for a JSON field of the body of a request or response. However, the "$." prefix is omitted in this syntax.

Example mappings from method request parameter in Swagger

The following example shows a Swagger snippet that maps 1) the method request's header, named methodRequestHeadParam, into the integration request path parameter, named integrationPathParam; 2) the method request query string, named methodRequestQueryParam, into the integration request query string, named integrationQueryParam.

Copy
... "requestParameters" : { "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam", "integration.request.querystring.integrationQueryParam" : "method.request.querystring.methodRequestQueryParam" } ...

Integration request parameters can also be mapped from fields in the JSON request body using a JSONPath expression. The following table shows the mapping expressions for a method request body and its JSON fields.

Example mapping from method request body in Swagger

The following example shows a Swagger snippet that maps 1) the method request body to the integration request header, named body-header, and 2) a JSON field of the body, as expressed by a JSON expression (petstore.pets[0].name, without the $. prefix).

Copy
... "requestParameters" : { "integration.request.header.body-header" : "method.request.body", "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name", } ...

Map Data to Method Response Headers

Method response header parameters can be mapped from any integration response header or from the integration response body.

Method response header mapping expressions

Mapped Data Source Mapping expression
Integration response header integration.response.header.PARAM_NAME
Integration response body integration.response.body
Integration response body (JsonPath) integration.response.body.JSONPath_EXPRESSION
Stage variable stageVariables.VARIABLE_NAME
Context variable context.VARIABLE_NAME that must be one of the supported context variables.
Static value 'STATIC_VALUE'. The STATIC_VALUE is a string literal and must be enclosed within a pair of single quotes.

Example data mapping from integration response in Swagger

The following example shows a Swagger snippet that maps 1) the integration response's redirect.url, JSONPath field into the request response's location header; and 2) the integration response's x-app-id header to the method response's id header.

Copy
... "responseParameters" : { "method.response.header.location" : "integration.response.body.redirect.url", "method.response.header.id" : "integration.response.header.x-app-id", } ...

Map Payloads between Requests and Responses

In API Gateway, mapping templates written in Velocity Template Language (VTL) are used to map method request payloads to the corresponding integration request payloads and to map integration response bodies to the method response bodies.

The VTL templates uses JSONPath expressions, other parameters such as calling contexts and stage variables, and utility functions to process the JSON data.

A payload can use a model to describe its shape or the data structure. However, a mapping template does not require a model to describe the data structure.

Select a Mapping Template

API Gateway uses the following logic to select a mapping template, in Velocity Template Language (VTL), to map the payload from a method request to the corresponding integration request or to map the payload from an integration response to the corresponding method response.

For a request payload, API Gateway uses the request’s Content-Type header value as the key to select the mapping template for the request payload. For a response payload, API Gateway uses the incoming request’s Accept header value as the key to select the mapping template.

When the Content-Type or Accept header is not specified in the request, API Gateway assumes that it takes application/json as the default value. Hence, for a request without the Content-Type header specified or for a response without the Accept header specified in the original request, API Gateway uses application/json as the default key to select the mapping template, if one is defined. When no template matches this key, API Gateway passes the payload through unmapped if the passthroughBehavior property is set to WHEN_NO_MATCH or WHEN_NO_TEMPLATES.

For example, if the client sends headers of "Content-Type : application/xml", and "Accept : application/json", the request template with the application/xml key will be used for the integration request, and the response template with the application/json key will be used for the method response.

Only the MIME type is used from the Accept and Content-Type headers when selecting a mapping template. For example, a header of "Content-Type: application/json; charset=UTF-8" will have a request template with the application/json key selected.