How Amazon API Gateway 's Body Mapping Templates On Integration Request Works?

Question

I am new to AWS API gateway world, and I followed as API documentation says e.g. also the defined example here

Now in my work requirements I would like to have complete caller's HTTP header, caller's IP address details as HTTP request received by API Gateway.

Yes I referred example as defined here , It talks about the $context variable, no where it talks about any example. Yes, I would like to then pass altered information ( via Body Mapping Template to Lambda Function).

Yes, I also referred talks about the Request Body Passthrough - with three options , I selected all three ? [as it says one by one - to understand their working],But its documentation is with all confusion, and no examples available , and nowhere it talks about 'Why'.

My Question :In what situation it will pick the specific template (as I defined 'application/sumit') ?, I tried to use all ways so that template defined by myself, that should be picked but it didn't happen e.g. I sent request from Postman and added content type "application/sumit' that means the content is not json, its my self-defined type, and it should be picked (as body stuff) and then sent to the connected Lambda function, but it didn't work the way I expected(I chose all three options one by one as the default case of doing stuff).

What exactly the meaning of all three options :

. When no template matches the request Content-Type header ( e.g. means If no Content-Type is abc/abc which doesn't match with any one, then what ?)Given Information : The request body will be passed through to the integration when there are no templates matching the request Content-Type header.

. When there are no templates defined ?(Recommended) (why its recommended ?, What is the reasoning behind it, Where we can find the answer of it ?)Given Information :The request body will be passed through to the integration only when there are no mapping templates defined.

. Never (it means that raw body straight forward should forward to Lambda function, but its not happening that way ?)Given Information :The request body will never be passed through to the integration. Requests with a Content-type header that don't match any templates will be rejected with a HTTP 415 response.

Answer 1

We're working on improving the documentation for this.

For now, we would simply recommend using the 2nd option ("when there are no templates defined").

This ensures that as long as you have request templates defined for your method, the request body from the client will never be "passed through" to the endpoint verbatim.

If the client sends "Content-Type" header that matches one of your templates, your mapping template will be applied to the request body and sent to the integration.

If the client sends "Content-Type" header that doesn't match any of your templates, the request will fail with a 415 error.

In some cases you may want to simply proxy the request body sent from the client to the integration. In these cases, the 1st option ("when no template matches") would be appropriate, but please be aware of the security implications of allowing the client to fully control the request body to your integration.