Intro

A common scenario is that we have an API with stages like dev and production and our endpoints are pointing to lambda functions. We want to be able to modify our lambda functions without breaking our production endpoints. To accomplish this we can use stage variables to point to different versions of our lambda functions.

Create Lambda Versions

The first step is to create a version of the stable lambda function that we can tie to our production stage. The dev endpoint can just use the $LATEST version of the lambda function.

Let’s say for example that we have a lambda function titled:

TEST_endpoint-versioning-with-alias

where the full ARN of the function would be this: arn:aws:lambda:us-east-1:123456789:function:TEST_endpoint-versioning-with-alias. Typically to point to version 1 and $LATEST you would reference the ARN like this:

arn:aws:lambda:us-east-1:123456789:function:TEST_endpoint-versioning-with-alias:1

arn:aws:lambda:us-east-1:123456789:function:TEST_endpoint-versioning-with-alias:$LATEST

however it is also important to note that the $LATEST version of the function is always available at the base ARN, so you can also reference it like this:

arn:aws:lambda:us-east-1:123456789:function:TEST_endpoint-versioning-with-alias

While making stage variables in API Gateway, we actually must reference the function that way, because $ is a disallowed character in stage variables.

Create Stage Variables

Inside API Gateway navigate to Stages > Stage Variables and in both stages create a variable with the same name where the value is just the name of the lambda function. So we would have the following values.

The reason we use just the name of the lambda function and not the full ARN is because the ARN is parsed automatically. If you try to use the full ARN you will get an error.

Reference the Stage Variables

In your endpoint configuration, you can now reference the stage variables like this:

${stageVariables.testLambda}

Just to be very clear, the stageVariables object that we are referencing there is automatically generated by API Gateway. You do not need to create it yourself.

Handling Permissions

One of the last things that we need to handle is giving API Gateway permission to invoke the lambda. Typically this is done automatically when you directly reference the lambda function in the endpoint configuration. However, since we are using stage variables, we need to manually add the permissions. Using the CLI we can do this with the following command:

aws lambda add-permission
--function-name "THE_ARN_OF_YOUR_LAMBDA_FUNCTION"  
--source-arn "arn:aws:execute-api:us-east-1:123456789:sd1pym93u4/*/POST/test"  
--principal apigateway.amazonaws.com  
--statement-id A-RANDOM-ID-OF-YOUR-CHOOSING  
--action lambda:InvokeFunction

Where you fill in the ARN of your lambda function, and the ARN of your API Gateway endpoint. You will likely be prompted with a modal that has generated this command for you, so you can just copy and paste it into your terminal.

I’ve formatted the command flags above on separate lines for readability, but you will need to remove the line breaks if you are copying and pasting the command. Actual format will be this:

aws lambda add-permission --function-name "THE_ARN_OF_YOUR_LAMBDA_FUNCTION" --source-arn "arn:aws:execute-api:us-east-1:123456789:sd1pym93u4/*/POST/test" --principal apigateway.amazonaws.com --statement-id A-RANDOM-ID-OF-YOUR-CHOOSING --action lambda:InvokeFunction

⚠ READ THIS: If you target a specific version of your lambda function, you will need to add permissions for that specific version, which just means that you need to modify the CLI command with an updated ARN, and a different statement ID. If you target a specific version with stage variables and you do not do this, you will get 500 permission errors and break your production API.

If you are using different lambda functions for each stage, you will need to add permissions for each lambda function.