Integration passthrough behaviors

With non-proxy integrations, when a method request carries a payload and either the Content-Type header does not match any specified mapping template or no mapping template is defined, you can choose to pass the client-supplied request payload through the integration request to the backend without transformation. The process is known as integration passthrough.

For proxy integrations, API Gateway passes the entire request through to your backend, and you do not have the option to modify the passthrough behaviors.

The actual passthrough behavior of an incoming request is determined by the option you choose for a specified mapping template, during integration request set-up, and the Content Type header that a client set in the incoming request. There are three options:

When no template matches the request Content-Type header

Choose this option if you want the method request body to pass through the integration request to the backend without transformation when the method request content type does not match any content types associated with the mapping templates.

When calling the API Gateway API, you choose this option by setting WHEN_NO_MATCH as the passthroughBehavior property value on the Integration.

When there are no templates defined (recommended)

Choose this option if you want the method request body to pass through the integration request to the backend without transformation when no mapping template is defined in the integration request. If a template is defined when this option is selected, the method request of an unmapped content type will be rejected with an HTTP 415 Unsupported Media Type response.

When calling the API Gateway API, you choose this option by setting WHEN_NO_TEMPLATES as the passthroughBehavior property value on the Integration.

Never

Choose this option if you do not want the method request body to pass through the integration request to the backend without transformation when no mapping template is defined in the integration request. If a template is defined when this option is selected, the method request of an unmapped content type will be rejected with an HTTP 415 Unsupported Media Type response.

When calling the API Gateway API, you choose this option by setting NEVER as the passthroughBehavior property value on the Integration.

The following examples illustrate the possible passthrough behaviors.

Example 1: One mapping template is defined in the integration request for the application/json content type.

Content-type header\Selected passthrough option	WHEN_NO_MATCH	WHEN_NO_TEMPLATES	NEVER
None (default to application/json)	The request payload is transformed using the template.	The request payload is transformed using the template.	The request payload is transformed using the template.
application/json	The request payload is transformed using the template.	The request payload is transformed using the template.	The request payload is transformed using the template.
application/xml	The request payload is not transformed and is sent to the backend as-is.	The request is rejected with an HTTP 415 Unsupported Media Type response.	The request is rejected with an HTTP 415 Unsupported Media Type response.

Example 2: One mapping template is defined in the integration request for the application/xml content type.

Content-type header\Selected passthrough option	WHEN_NO_MATCH	WHEN_NO_TEMPLATES	NEVER
None (default to application/json)	The request payload is not transformed and is sent to the backend as-is.	The request is rejected with an HTTP 415 Unsupported Media Type response.	The request is rejected with an HTTP 415 Unsupported Media Type response.
application/json	The request payload is not transformed and is sent to the backend as-is.	The request is rejected with an HTTP 415 Unsupported Media Type response.	The request is rejected with an HTTP 415 Unsupported Media Type response.
application/xml	The request payload is transformed using the template.	The request payload is transformed using the template.	The request payload is transformed using the template.