API Gateway doesn't just receive requests — it must forward them to a backend and relay the response. The integration type determines exactly how this handoff works. Choosing the wrong integration type is a common source of subtle bugs and unnecessary complexity.
Lambda Proxy Integration (Most Common)
API Gateway passes the entire HTTP request — method, path, headers, query string, body, and request context — to your Lambda as a structured JSON event. Your Lambda is responsible for parsing this event and returning a properly formatted response object.
{
"statusCode": 200,
"headers": { "Content-Type": "application/json" },
"body": "{\"message\": \"Hello, World\"}"
}
Advantage: Simple. No configuration in API Gateway. Your Lambda has full control.
Disadvantage: Your Lambda must understand the API Gateway event format. It's tightly coupled to API Gateway's contract.
Lambda Non-Proxy (Custom) Integration
API Gateway transforms the request before sending it to Lambda, using VTL (Velocity Template Language) mapping templates. The Lambda receives a clean, custom-shaped payload — it doesn't need to know it's being called from API Gateway.
Advantage: Decouples your Lambda from API Gateway's event format. The same Lambda can be invoked from API Gateway, SQS, or directly — it just receives a clean business object.
Disadvantage: VTL is a complex templating language. Mapping templates are difficult to test and debug.
HTTP Integration
Forwards the request to any public HTTP endpoint — an EC2 instance, an on-premises server, or a third-party API. Useful for migrating legacy backends behind API Gateway without rewriting them as Lambda functions.
AWS Service Integration
Directly invokes an AWS service (SQS, DynamoDB, SNS, Step Functions) without a Lambda in the middle. For example, a POST /orders endpoint can write directly to an SQS queue using a VTL mapping template — no Lambda required.
POST /orders → API Gateway → SQS SendMessage (direct integration)
This pattern reduces cost (no Lambda invocation) and latency (one fewer network hop) for simple pass-through operations.