Amazon API Gateway API request and response data mapping reference

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 method request 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.

In the following table, PARAM_NAME is the name of a method request parameter of the given parameter type. It must match the regular expression '^[a-zA-Z0-9._$-]+$]'. 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.

...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.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.

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

Map integration response data to method response headers

Method response header parameters can be mapped from any integration response header or integration response body, $context variables, or static values.

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

Map request and response payloads between method and integration

API Gateway uses Velocity Template Language (VTL) engine to process body mapping templates for the integration request and integration response. The mapping templates translate method request payloads to the corresponding integration request payloads and translate integration response bodies to the method response bodies.

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

If a model is defined to describe the data structure of a payload, API Gateway can use the model to generate a skeletal mapping template for an integration request or integration response. You can use the skeletal template as an aid to customize and expand the mapping VTL script. However, you can create a mapping template from scratch without defining a model for the payload's data structure.

Select a VTL 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 header is absent in the request, API Gateway assumes that its default value is application/json. For such a 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.

When the Accept header is not specified in the request, API Gateway assumes that its default value is application/json. In this case, API Gateway selects an existing mapping template for application/json to map the response payload. If no template is defined for application/json, API Gateway selects the first existing template and uses it as the default to map the response payload. Similarly, API Gateway uses the first existing template when the specified Accept header value does not match any existing template key. If no template is defined, API Gateway simply passes the response payload through unmapped.

For example, suppose that an API has a application/json template defined for a request payload and has a application/xml template defined for the response payload. If the client sets the "Content-Type : application/json", and "Accept : application/xml" headers in the request, both the request and response payloads will be processed with the corresponding mapping templates. If the Accept:application/xml header is absent, the application/xml mapping template will be used to map the response payload. To return the response payload unmapped instead, you must set up an empty template for application/json.

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.