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
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.
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.
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.
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.
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.
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:
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:
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.
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.
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 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 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).
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 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 represent the response’s headers, status codes and the associated response and body mapping template.
- Lambda-Proxy: If you want a simple Integration, and don’t need swagger specifications or any other filters.
- Lambda Integration: If you need to have more control on workflow, generate sophisticated documentation and SDK generation.
- Use Serverless framework, as it automates a lot of manual steps, especially in the case of Lambda Integration.