How to Use API Gateway with AWS Lambda Versioning and Aliases

2021/1/3·5 min read

This blog shows how to build a simple API Gateway REST API with AWS Lambda. We'll also use AWS Lambda versioning and aliases to switch to a different version by using Node.js.

At here, we'll create a Lambda function by using Node.js, then we're going to create 2 versions of it and each will return a different value. Finally will create an alias as prod which will map version 1, furthermore, we'll switch from version 1 to version 2 and check the result. For the API gateway, will create a public REST API and connect to the Lambda we just create.

Setup AWS Account

First, you'll need to have an AWS account, if you don't you can create an AWS Free Tier account which will be free of charge for a one-year period. However the AWS Lambda and API Gateway are very cheap, for instance, $0.20 per 1 M requests to use Lambda, for API Gateway, the first 333 million is $3.5, which's pretty cheap if you think about you don't have to host the server. 

Create Lambda Function

Create Lambda function from scratch

Here, go to the Lambda and clicked create function, then choose the Author from scratch.

Enter the function name, for example, let's use myLambdaTest.

Choose Node.js 14.x, so we'll be using Node.js and use version 14.

You can skip the entire Advance Setting, but if you need to use your own VPC, subnet, or security group you can use the advance setting to modify the setting you prefer.

You should be able to see your Lambda function, click the index.js, and should be able to see the default code snippet provide by AWS.

exports.handler = async (event) => {
    // TODO implement
    const response = {
        statusCode: 200,
        body: JSON.stringify('Hello from Lambda!'),
    return response;

Publish new version

click publish the new version and enter the description, this then will become our version 1.

Create alias

Go to the lambda function, click action then click Create an alias. Enter the alias name, here we'll use prod. For the version, let's choose version 1. Now, here is the important thing for this blog, we notice our lambda alias prod is mapping to version 1 now. 

Also, check the lambda function ARN, you should see something as follows. Please note this, please later we'll use this at the API gateway. 


Modify the Lambda and publish a new version

Now, here we'll go back to the Lambda modify the response as follows. We basically just modify the response, after the change click deploys and then click action to publish a new version.

exports.handler = async (event) => {
    // TODO implement
    const response = {
        statusCode: 200,
        body: JSON.stringify('Hi'),
    return response;

At this point, we have 2 versions of our Lambda, one returns the 'Hello from Lambda' which is version 1 another is returning 'Hi' which is version 2, and alias prod is using version 1. 

Create API Gateway

Here, we'll create public REST API and use the Lambda we just created as back-end. 

Go to the API Gateway, then click REST API's build button.

Choose New API and enter API name. 

Create Resource

at the API, click Actions, and then click Create Resource.

Enter the resource name and resource path.

Create Method

At the resource, we just created, click actions then click create method, here we'll create an HTTP method for the resource we have. We'll use Any for now, but you can specify to get, post, put or delete. 

On the setup page, make sure the integration type is Lambda Function, at the Lambda function field choose the Lambda name we just created earlier. You should see myLambdaTest, nowhere is the important part, instead of using this name we would apply the alias prod, so we change the name as follows. 


click ok, so this API gateway is integrated with lambda's alias prod now. The reason, we're doing it in this way is you can have control of what version to use for API Gateway to execute the Lambda.  

Test API Gateway

Now, our API gateway is pretty much finished, let's click the test button to test the API gateway. 

Click the Test, choose the Method as Get, you'll see the response shows 'Hello from Lambda!", that's our lambda's version 1.

Now, we'd like to update our lambda's alias's prod to point to version 2. 

Go back to the Lambda function, click the Aliases tab and choose the prod then click Edit. 

At the Edit alias window, change Version 1 to version 2 and click the save button.

Now, go back to the API Gateway and test the API gateway again, you'll notice the response body is 'Hi' now. So use lambda will have the flexibility of how you can deploy the Lambda function, you can do blue/green deployment or split the load to each version. 

Publish API Gateway

Click the Actions then click the Deploy API. At Deployment Stage, choose New Stage. Enter the Stage name then click the Deploy button. 

Now, at the stage editor page, you should have a URL, run the URL will run the Lambda function behind the scene and give you the same result. 


This blog just simply shows how to create REST API with Lambda function and how to switch Lambda version with aliases.