Versioning and Aliasing the Lambda Function

Lab Steps

Logging in to the Amazon Web Services Console
Understanding RESTful APIs
Defining New API Gateway Resources
Creating an AWS Lambda Function Backend
Versioning and Aliasing the Lambda Function
Configuring the API Gateway Backend
Following Best Practices for Versions, Aliases, and Stages
Creating API Keys and Usage Plans
Enabling CORS on API Gateway Resources
Enabling API Gateway Caching and Throttling
Cleaning up API Resources and Lambda Functions
Need help? Contact our support team

Here you can find the instructions for this specific Lab Step.

If you are ready for a real environment experience please start the Lab. Keep in mind that you'll need to start from the first step.


In this Lab Step, you will create different versions of the Lambda function corresponding with the dev and prod stages you created in API Gateway.

Each Lambda function has a default $LATEST version, which is the one you can always work on and edit. Once your code is stable enough or whenever your code changes significantly, you can create a new version. A simple incremental number will be assigned to the new version and you will be able to use and test any version. As you can imagine, this is a useful mechanism to keep track of your functions history and eventually rollback to previous versions.

Using versions is helpful, but sometimes even that is not flexible enough. For example, you can only bind your API Gateway resources and methods to a specific version of your Lambda function: whenever you create a new Lambda Version, you'd need to update your API Gateway configuration as well. Fortunately, AWS provides the concept of alias to improve this situation.

An alias is a useful abstraction that allows you to refer to a function version without actually using a version number. For example, you may want to create a prod alias and connect it to your API Gateway production stage. You could do the same with a dev alias, bound to your development stage. 

The best practice would be always referencing to aliases when configuring your API Gateway backend integrations. By default, API Gateway will point to the $LATEST version, but you can always configure it to use a specific version or alias.

The following are examples of how the version and alias mappings work:

  • ItemsFunction -> $LATEST Version
  • ItemsFunction:1 -> Version 1
  • ItemsFunction:prod -> prod alias -> Version 1

You will now create a new version and two new aliases for the Lambda function.



1. In the Lambda ItemsFunction Console, click Actions > Publish new version, optionally insert a Version description and click Publish:


Please note that you cannot modify published versions. You can only work on the $LATEST version.


2. Click Actions > Create alias and first create an alias for the dev stage by entering the following values before clicking Create:

  • Name: dev
  • DescriptionDevelopment alias
  • Version: $LATEST


The dev stage will always work with the latest version of the function. By binding the dev alias to our $LATEST version, you will be able to quickly implement changes and test them without explicitly publishing new versions. Of course, you can always adapt this configuration to your own needs. You usually don't want to be so aggressive in automatically releasing the latest function to production. You will alias prod to a specific version instead.


3. Click Actions > Create alias and enter the following values before clicking Create:

  • Nameprod
  • Description: Production alias
  • Version: 1


4. Click on Alias: prod to the left of the Actions drop-down menu to reveal the aliases and versions:


When no alias is selected (the Unqualified alias is selected), the menu is labeled Qualifiers. You can use the Qualifiers menu to switch between versions of the function.



Now that the Lambda function is configured with versions and aliases, you can use it as an API Gateway backend. In the next step, you will properly configure API Gateway resources to use the Lambda function.