Sign in Subscribe
4 min read AWS

AWS Serverless: Enable API Versioning via API Gateway + Lambda Aliases

After exposing the lambda function as an API for your serverless application, it is also necessary to keep the API manageable through version control.

Why Versioning?

  • Consistent: Versioning gives developers the ability to continuously work on the API without breaking or changing its delivered functionality by creating a separate version. For example, for a simple API /getreport, it would be benificial to have two endpoints: api.example.com/prod/getreport and api.example.com/dev/getreport. Which prod is the production stable release which should always be up and working, while developers will use dev version to develop and test new features.
  • Backup/Rollback: Although the latest stable version should always be up and working, however sometimes it does break unexpectedly. With the power of versioning, when this happens, the API is always able to rollback to its previous stable version to get everything back online again.

Create API Versioning

If you exposed a lambda function as an API in API Gateway, creating versioning of it requires 2 steps:

  • Create aliases on the lambda function for different version
  • Deploy the lambda function aliases to different API stages

Create aliases for Lambda Function

In AWS Console, open Lambda Management Console, in the top menu, click Actions > Publish new version.

In the pop-up dialog, fill in the version description, this can be anything (like v0.1, dev, stable, etc.).
Click "Finish", then you should see the new published version under Qualifiers > Versions.

Note that under "Versions" tab, you will see there are two available version:

  • The version you just published (which is version 1)
  • $LATEST

The version $LATEST points to the latest changes of the lambda function, every time we modify the function, $LATEST will save that change.

The version we published earlier keeps the change at the time we published it, once the version has been published, it is not modifiable, but it can be deleted.

Once the new version has been published, create an alias called "prod" for version 1 (which is the most recent stable release by far) by clicking Actions > Create alias.

Fill in the name, description, and version number (which is 1 in our case) in the dialog.

Repeat this for another alias called dev (which is the latest development version that will be worked on and not stable).

Once done, now we should have two alias for our lambda function: prod and dev, pointing to the version 1 and version $LATEST, respectively.

Deploy a multi-stage API via API Gateway

Since we already have multiple versions of the lambda function, the next step is to add additional stages to the API.
Let's take the previous example /getreport, in this case, the API should have two stages:

  • Development stage (endpoint: <API_URI>/dev/getreport)
  • Production stage (endpoint: <API_URI>/prod/getreport)

Go to API Gateway console, and click the API we want to modify (/getreport), then go to Resources Tab.

Under Resources, click Actions > Deploy API to deploy the production stage of the API /getreport:

Do the same thing to deploy the development version.

After that, go to Stages tab, click on prod stage, add a stage variable under Stage Variables tab with following value:

{
    Name: lambdaAlias,
    Value: stable
}

Create a stage variable for dev stage as well:

{
    Name: lambdaAlias,
    Value: dev
}

The name and value for stage variables can be anything, but the name for two stages should be consistent, if the name is lambdaAlias in stage prod, in stage dev the variable name should be lambdaAlias as well.

Then, click the method we want to add the versioning, on the right panel, click Integration Request.

ANY means all method

In the right panel, configure the lambda function as

<lambda>:${stageVariable.lambdaAlias}

Replace <lambda> with the lambda function we configured the versioning before.

Click the checkmark, then add the appropriate permission using AWSCLI for the Lambda Function by copying the command in the pop-up dialog.
The command should be something looks like the following:

aws lambda add-permission
    --function-name "arn:aws:lambda:<AWS_REGION>:<ARN_NUMBER>:function:<lambda>:${stageVariables.lambdaAlias}"
    --source-arn "arn:aws:execute-api:<AWS_REGION>:<ARN_NUMBER>:<ENDPOINT>"
    --principal apigateway.amazonaws.com
    --statement-id 5cce4d58-29eb-4e72-88b2-72df38c38f0f
    --action lambda:InvokeFunction

Run the command twice, replace ${stageVariables.lambdaAlias} with each lambdaAlias stage variable that created earlier (stable and dev).

When done, the API /getreport should have two endpoint available:

  • <API_URI>/prod/getreport: The production stage, this should always be up and stable.
  • <API_URI>/dev/getreport: Developers can use this endpoint for development and testing.

Creating versioning for API is important, especially for large-scaled applications, in the future there might be more versions rather than just two, and it is always welcome to reference this article as a guide to publish additional version of Lambda Function and APIs.

Published by:

Mike Xiao