Lambda-Proxy vs Lambda Integration in AWS API Gateway

Lambda-Proxy vs Lambda

AWS API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. Lambda is function as a service(FAAS) product of AWS. The combination of these two services is amazing and it is slowly replacing the traditional backend. The combination is serverless, cost-efficient and infinitely scalable.

API Gateway has many integrations, but this post is all about the possible integrations between API Gateway and Lambda. The two possible integrations are Lambda-Proxy and Lambda. I had a tough time understanding them, so I am going to document their features, pros, cons and instructions to setup in a comprehensible way. If you know about them and just want to set it up, jump to the instructions part.

High Level Technical Architecture

General Description

Request and Response



Enough of all the differences and explanations, time to get our hands dirty. I will start with Lambda-Proxy setup followed by Lambda integration setup.

Lambda-Proxy Setup

Assuming you have API Gateway and lambda in place, the following screenshot will show you, how to setup the Lambda-Proxy integration between API Gateway and Lambda.

Lambda-Proxy Setup

Make sure, you check the Use Lambda Proxy Integration check box, which will establish an integration of type Lambda-Proxy between API Gateway’s method and the associated Lambda function. Lets see how to send the success and error responses from the Lambda.

Success Response in Lambda-Proxy

The event parameter has the whole request object sent from the client. As you can see, the status code and headers has to be set inside the Lambda. Make sure you send the response as second argument to the callback.

Note: The first argument to the callback is for sending error to client. We will see that in coming section.

Error Response in Lambda-Proxy

Here is the sample error response in Lambda-proxy. You can set various status codes depending on the error type in statusCode attribute.

Note: Even though callback’s first argument is for error, it is not descriptive. It will just send an 502 error code irrespective on the type of error. So, make sure you use the above setup for specifying the error in Lambda-Proxy integration. In addition to that, Lambda-Proxy expects the same attributes in response namely statusCode, headers and body else, it will throw a 502 (Bad Gateway) error.

serverless.yml file for Lambda-Proxy

Lambda-Proxy Setup in Serverless Framework: By default, serverless framework uses Lambda-Proxy integration. When you add http event to the Lambda function, a Lambda-Proxy integration will be created.

Lambda Integration Setup

This is going to be long, as it requires too many configurations in the API Gateway. Initially, in the API Gateway console, select the Lambda Function option in Integration Type. See the screenshot below for a better understanding:

Lambda Integration Setup

Make sure, you don’t check the Use Lambda Proxy Integration option. Once you save it, you have integrated API Gateway and the Lambda using Lambda Integration. After accepting the popping dialog box, you will be shown the request & response workflow. Here is the workflow screen you will see:

Request Workflow in Lambda Integration

Method Request is the request originated from the client. The Integration Request is the transformation that you can do with API Gateway. The request body can be transformed as per your body mapping template. Once the Lambda process it and responds, it then reaches Integration Response. This is where, you can assign appropriate status code and do response transformation, if present. After the transformation, the response is sent to client.

Integration Request is the part, where you transform the request by using the mapping template defined as per content-type. A mapping template is a script expressed in Velocity Template Language (VTL) and applied to the request payload using JSONPath expressions. Here is an example of mapping template for the application/json content-type.

Integration Request

Navigating to Integration Request section, will list all the options for transforming request like adding custom headers, query parameters and body templates. The above screenshot shows the mapping template for application/json content-type. Now, the transformed request will invoke the associated Lambda. Lets see how to send the success and error responses from the Lambda.

Success Response in Lambda Integration

The success response is similar to Lambda-Proxy, but you don’t have to specify the status code and the headers. As I pointed out earlier, status code and header will be set by API Gateway in Integration Response. Status codes are assigned based on the Regex pattern you define in the Integration Response. Here is the Integration Response for 200 status code.

200 Integration Response

200 status code doesn’t have any Regex defined. It is the default mapping. So all the responses from Lambda are considered as 200 responses. If you don’t define Regex patterns for error status code, then even error responses are sent with 200 status code. Now, jumping onto error responses in Lambda Integration.

Error Integration Response

Error responses in Lambda Integration are sent as first argument to the callback. It has to be stringified, which makes the Integration Response to read the error response and assign appropriate status code based on the defined Regex. For the given example, I want to set 400 as error status code, if the message has the keyword wrong. Here is the Integration Response for the 400 (error code).

400 Integration Response

As you can see, once the wrong keyword is detected, it assigns the 400 status code. I have also added a mapping template to transform the error response. This is how you set status code, headers and assign template to the response. Swagger specifications can be exported for the API with all status codes from the API Gateway console. This makes the documentation and SDK generation much easier.

Lambda Integration in serverless.yml

Lambda Integration Setup in Serverless Framework: You have to define the Lambda integration explicitly in serverless.yml file. Line 8, shows the integration of the function. Lines 9 - 12 represents the request body mapping template based on various content-type. Lines 13 - 22 represents the response’s headers, status codes and the associated response and body mapping template.


  1. Lambda-Proxy: If you want a simple Integration, and don’t need swagger specifications or any other filters.
  2. Lambda Integration: If you need to have more control on workflow, generate sophisticated documentation and SDK generation.
  3. Use Serverless framework, as it automates lot of manual steps, especially in case of Lambda Integration.

Thank you for reading. If you find something wrong or better ways to do it, let me know in the comments below.

If you like the post, hit the 👏 button below so that others may find it useful. You can follow me on Twitter.