Using Amazon API Gateway stage variables
You can use API Gateway stage variables to access the HTTP and Lambda backends for different API deployment stages. You can also use stage variables to pass stage-specific configuration metadata into an HTTP backend as a query parameter and into a Lambda function as a payload that is generated in an input mapping template.
Prerequisites
You must create two stages with a url stage variable set to two different HTTP endpoints: a function stage variable assigned to two different Lambda functions, and a stageName stage variable containing stage-specific metadata.
Access an HTTP endpoint through an API with a stage variable
-
In the Stages navigation pane, choose beta. Under Stage details, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser. This starts the beta stage
GET
request on the root resource of the API.Note
The Invoke URL link points to the root resource of the API in its beta stage. Entering the URL in a web browser calls the beta stage
GET
method on the root resource. If methods are defined on child resources and not on the root resource itself, entering the URL in a web browser returns a{"message":"Missing Authentication Token"}
error response. In this case, you must append the name of a specific child resource to the Invoke URL link. -
The response you get from the beta stage
GET
request is shown next. You can also verify the result by using a browser to navigate to http://httpbin.org/get. This value was assigned to theurl
variable in the beta stage. The two responses are identical. -
In the Stages navigation pane, choose the prod stage. Under Stage details, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser. This starts the prod stage
GET
request on the root resource of the API. -
The response you get from the prod stage
GET
request is shown next. You can verify the result by using a browser to navigate to http://petstore-demo-endpoint.execute-api.com/petstore/pets. This value was assigned to theurl
variable in the prod stage. The two responses are identical.
Pass stage-specific metadata to an HTTP backend through a stage variable in a query parameter expression
This procedure describes how to use a stage variable value in a query parameter expression to pass
stage-specific metadata into an HTTP backend. We will use the stageName
stage variable declared in
Setting stage variables using the Amazon API Gateway
console.
-
In the Resource navigation pane, choose the GET method.
To add a query string parameter to the method's URL, choose the Method request tab, and then in the Method request settings section, choose Edit.
Choose URL query string parameters and do the following:
Choose Add query string.
For Name, enter
stageName
.Keep Required and Caching turned off.
Choose Save.
-
Choose the Integration request tab, and then in the Integration request settings section, choose Edit.
For Endpoint URL, append
?stageName=${stageVariables.stageName}
to the previously defined URL value, so the entire Endpoint URL ishttp://${stageVariables.url}?stageName=${stageVariables.stageName}
.-
Choose Deploy API and select the beta stage.
-
In the main navigation pane, choose Stages. In the Stages navigation pane, choose beta. Under Stage details, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser.
Note
We use the beta stage here because the HTTP endpoint (as specified by the
url
variable "http://httpbin.org/get") accepts query parameter expressions and returns them as theargs
object in its response. -
You get the following response. Notice that
beta
, assigned to thestageName
stage variable, is passed in the backend as thestageName
argument.
Call a Lambda function through an API with a stage variable
This procedure describes how to use a stage variable to call a Lambda function as a backend of your API. We
will use the function
stage variable declared earlier. For more information, see Setting stage variables using the Amazon API Gateway
console.
-
Create a Lambda function named
HelloWorld
using the default Node.js runtime. The code must contain the following:export const handler = function(event, context, callback) { if (event.stageName) callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.'); else callback(null, 'Hello, World! I\'m not sure where I\'m calling from...'); };
For more information on how to create a Lambda function, see Getting started with the REST API console.
-
In the Resources pane, select Create resource, and then do the following:
For Resource path, select /.
For Resource name, enter
lambdav1
.Choose Create resource.
-
Choose the /lambdav1 resource, and then choose Create method.
Then, do the following:
For Method type, select GET.
For Integration type, select Lambda function.
Keep Lambda proxy integration turned off.
For Lambda function, enter
${stageVariables.function}
.Tip
When prompted with the Add permission command, copy the AWS CLI command. Run the command on each Lambda function that will be assigned to the
function
stage variable. For example, if the$stageVariables.function
value isHelloWorld
, run the following AWS CLI command:aws lambda add-permission --function-name arn:aws:lambda:us-east-1:
account-id
:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id
:api-id
/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-idstatement-id-guid
--action lambda:InvokeFunctionFailing to do so results in a
500 Internal Server Error
response when invoking the method. Replace${stageVariables.function}
with the Lambda function name that is assigned to the stage variable.-
Choose Create method.
-
Deploy the API to both the
prod
andbeta
stages. -
In the main navigation pane, choose Stages. In the Stages navigation pane, choose beta. Under Stage details, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser. Append
/lambdav1
to the URL before you press enter.You get the following response.
"Hello, World! I'm not sure where I'm calling from..."
Pass stage-specific metadata to a Lambda function through a stage variable
This procedure describes how to use a stage variable to pass stage-specific configuration metadata into a
Lambda function. You create a POST
method and an input mapping template to generate payload using
the stageName
stage variable you declared earlier.
-
Choose the /lambdav1 resource, and then choose Create method.
Then, do the following:
For Method type, select POST.
For Integration type, select Lambda function.
Keep Lambda proxy integration turned off.
For Lambda function, enter
${stageVariables.function}
.When prompted with the Add permission command, copy the AWS CLI command. Run the command on each Lambda function that will be assigned to the
function
stage variable.Choose Create method.
-
Choose the Integration request tab, and then in the Integration request settings section, choose Edit.
Choose Mapping templates, and then choose Add mapping template.
For Content type, enter
application/json
.For Template body, enter the following template:
#set($inputRoot = $input.path('$')) { "stageName" : "$stageVariables.stageName" }
Note
In a mapping template, a stage variable must be referenced within quotes (as in
"$stageVariables.stageName"
or"${stageVariables.stageName}"
). In other places, it must be referenced without quotes (as in${stageVariables.function}
).Choose Save.
-
Deploy the API to both the
beta
andprod
stages. -
To use a REST API client to pass stage-specific metadata, do the following:
In the Stages navigation pane, choose beta. Under Stage details, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in the input field of a REST API client. Append
/lambdav1
before you submit your request.You get the following response.
"Hello, World! I'm calling from the beta stage."
In the Stages navigation pane, choose prod. Under Stage details, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in the input field of a REST API client. Append
/lambdav1
before you submit your request.You get the following response.
"Hello, World! I'm calling from the prod stage."
-
To use the Test feature to pass stage-specific metadata, do the following:
In the Resources navigation pane, choose the Test tab. You might need to choose the right arrow button to show the tab.
For function, enter
HelloWorld
.For stageName, enter
beta
.Choose Test. You do not need to add a body to your
POST
request.You get the following response.
"Hello, World! I'm calling from the beta stage."
You can repeat the previous steps to test the Prod stage. For stageName, enter
Prod
.You get the following response.
"Hello, World! I'm calling from the prod stage."