Gateway responses for REST APIs in API Gateway
A gateway response is identified by a response type that is defined by API Gateway. The response consists of an HTTP status code, a set of additional headers that are specified by parameter mappings, and a payload that is generated by a non-VTL mapping template.
In the API Gateway REST API, a gateway response is represented by the GatewayResponse. In OpenAPI, a
GatewayResponse instance is described by the x-amazon-apigateway-gateway-responses.gatewayResponse extension.
To enable a gateway response, you set up a gateway response for a supported response type at the API level. Whenever API Gateway returns a response of this type, the header mappings and payload mapping templates defined in the gateway response are applied to return the mapped results to the API caller.
In the following section, we show how to set up gateway responses by using the API Gateway console and the API Gateway REST API.
Setting up gateway responses to customize error responses
If API Gateway fails to process an incoming request, it returns to the client an error
response without forwarding the request to the integration backend. By default, the
error response contains a short descriptive error message. For example, if you attempt
to call an operation on an undefined API resource, you receive an error response with
the { "message": "Missing Authentication Token" } message. If you are new
to API Gateway, you may find it difficult to understand what actually went wrong.
For some of the error responses, API Gateway allows customization by API developers to
return the responses in different formats. For the Missing Authentication
Token example, you can add a hint to the original response payload with the
possible cause, as in this example: {"message":"Missing Authentication Token",
"hint":"The HTTP method or resources may not be supported."}.
When your API mediates between an external exchange and the AWS Cloud, you use VTL mapping templates for integration request or integration response to map the payload from one format to another. However, the VTL mapping templates work only for valid requests with successful responses.
For invalid requests, API Gateway bypasses the integration altogether and returns an error response. You must use the customization to render the error responses in an exchange-compliant format. Here, the customization is rendered in a non-VTL mapping template supporting only simple variable substitutions.
Generalizing the API Gateway-generated error response to any responses generated by API Gateway,
we refer to them as gateway responses. This distinguishes
API Gateway-generated responses from the integration responses. A gateway response mapping
template can access $context variable values and
$stageVariables property values, as well as method request parameters,
in the form of
method.request.. param-position.param-name
For more information about $context variables, see $context Variables for data
models, authorizers, mapping templates, and CloudWatch access logging.
For more information about $stageVariables, see $stageVariables. For more information about
method request parameters, see $input Variables.
Topics
