aws api gateway - Lambda Integration vs. Lambda Proxy: Pros and Cons

Question

What do you think are the Pros and Cons of using Lambda integration with and without the proxy feature in AWS API Gateway (and more specifically, when using the Serverless framework)? Here's what I think up to now:

Lambda Integration with Proxy

• Pro: One can rapidly prototype and code without worrying about all the needed configuration details (and reinventing a few wheels like generic template mappings, etc).
• Pro: It's really easy to return any status code and custom headers, while at the same time there's a generic way to read the body, headers, parameters, of the request.
• Con: Everything is done in code, so autogenerating documentation is a bit more difficult. Dependencies (headers, models, returned status codes) are "hidden" in the code.

Lambda Integration without Proxy

• Con: Involves a lot more of work to set it up, and this configuration might be duplicated in different resources.
• Pro: It allows one to decouple what the lambda receives and returns, and how it gets mapped to different HTTP status codes, headers, and payloads.
• Pro: Very useful because it stipulates upfront what it returns, and what it requires in terms of headers and payloads.
• Pro: The hard work when setting up everything is useful in the long run because one can export everything to Swagger, so others can use this to generate different SDKs for it.

What are your thoughts? Do you generally use Lambda Proxy or plain Lambda integrations? What do you prefer, and why?

EDIT: So far, I'm inclined to always choose not to use the proxy features due to the reasons mentioned (decoupling and stating dependencies -headers, status codes, etc- upfront).

Answer 1

(Edit: As noted in the comments, the AWS verbiage I called out in 2018 has been removed. That said, my thoughts regarding Lambda proxy vs. custom integration still hold.)

It looks like AWS recommends choosing Lambda Proxy Integration for new API development.

Note

The Lambda custom integration, formerly known as the Lambda integration, is a legacy technology. We recommend that you use the Lambda proxy integration for any new API. For more information, see Build an API Gateway API with Lambda Proxy Integration

I understand that it's a lot "quicker" (in the short term) to spin up an API endpoint and lambda integration using proxy integration rather than the custom integration, but I'm surprised that it's the recommendation for all API / Lambda development going forward:

• I pictured API Gateway as being responsible for handling the "HTTP details". Using Proxy Integration forces (at least a subset of) that responsibility onto the Lambda function. (i.e. knowing how to interpret and decide on HTTP headers, query parameters, status codes, etc.)
• In doing that, I feel that it muddies the responsibility of the backing Lambda function -- Lambda now needs to both handle whatever "business" logic it's being called to do, and also handle interpreting the incoming HTTP values and decide on the outgoing HTTP response values.
• Granted, you could implement an additional Lambda function layer to abstract away the HTTP details, but isn't that what API Gateway is supposed to do?
• It reduces the ability to re-use any given Lambda function in a context other than servicing HTTP requests, unless non-HTTP clients format the request as if it were an HTTP request.