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.

You can pause this lab for
(up to) 1h


In this lab step, you will create different versions of the AWS 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 AWS Lambda console, click the Versions tab, and click Publish new version:


A form will open allowing you to optionally specify a description of the new version.


2. To publish a new version, click Publish:


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

Next, you will create an alias for your AWS Lambda function.


3. At the top-right, click Actions, click the Create alias menu item, and enter the following form values:

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


You are creating an alias for the dev stage.

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.


4. To save your alias and return to the function's details page, click Save, and then at the top click ItemsFunction.


5. To create an alias for production, at the top click ActionsCreate alias and enter the following form values:

  • Nameprod
  • Description: Production alias
  • Version: Select the number (not $LATEST)

Notice the Weighted alias option. Traffic to an AWS Lambda function can be split between multiple versions. This allows you to test a new version of a function on a subset of traffic before fully deploying it. Weighted aliases aren't used in this lab.


6. To save your alias and return to the function's details page, click Save, and then at the top click ItemsFunction.


7. To see the aliases you created, click the Aliases tab:


You will see the dev and prod aliases listed.

You can also see the version you published by clicking on the Versions tab.



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.