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 variable set to two different HTTP endpoints: a function stage variable assigned to two different Lambda functions, and a version stage variable containing stage-specific metadata. Follow the instructions in Setting stage variables using the Amazon API Gateway console.

Access an HTTP endpoint through an API with a stage variable

1. In the Stages navigation pane, choose beta. In beta Stage Editor, choose the Invoke URL link. 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. Navigating to the URL by choosing the link calls the beta stage GET method on the root resource. If methods are defined on child resources and not on the root resource itself, choosing the Invoke URL link 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.

2. 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 the url variable in the beta stage. The two responses are identical.

3. In the Stages navigation pane, choose the prod stage. From prod Stage Editor , choose the Invoke URL link. This starts the prod stage GET request on the root resource of the API.

4. 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 the url 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 version stage variable declared in Setting stage variables using the Amazon API Gateway console.

1. In the Resource navigation pane, choose the GET method. To add a query string parameter to the method's URL, in Method Execution, choose Method Request. Enter version for the parameter name.

2. In Method Execution choose Integration Request. Edit the Endpoint URL value to append ?version=${stageVariables.version} to the previously defined URL value, which, in this case, is also expressed with the url stage variable. Choose Deploy API to deploy these changes.

3. In the Stages navigation pane, choose the beta stage. From beta Stage Editor, verify that the current stage is in the most recent deployment, and then choose the Invoke URL link.

   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 the args object in its response.

4. The response is shown next. Notice that v-beta, assigned to the version stage variable, is passed in the backend as the version 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.

1. In the Resources pane, create a /lambdasv1 child resource under the root directory, and then create a GET method on the child resource. Set the Integration type to Lambda Function, and in Lambda Function, enter ${stageVariables.function}. Choose Save.

   

   Tip

   When prompted with Add Permission to Lambda Function, make a note of the AWS CLI command before choosing OK. You must run the command on each Lambda function that is or will be assigned to the function stage variable for each of the newly created API methods. For example, if the $stageVariables.function value is HelloWorld and you have not added permission to this function yet, you must 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/lambdasv1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction

   Failing to do so results in a 500 Internal Server Error response when invoking the method. Make sure to replace ${stageVariables.function} with the Lambda function name that is assigned to the stage variable.

   

2. Deploy the API to available stages.

3. In the Stages navigation pane, choose the beta stage. Verify that your most recent deployment is in beta Stage Editor. Copy the Invoke URL link, paste it into the address bar of your browser, and append /lambdasv1 to that URL. This calls the underlying Lambda function through the GET method on the LambdaSv1 child resource of the API.

   Note

   Your HelloWorld Lambda function implements the following code.

   
   export const handler = function(event, context, callback) {
       if (event.version)
           callback(null, 'Hello, World! (' + event.version + ')' );
       else
           callback(null, "Hello, world! (v-unknown)");  
   };
               

   This implementation results in the following response.

   "Hello, world! (v-unknown)"

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. We will use a POST method and an input mapping template to generate payload using the version stage variable declared earlier.

1. In the Resources pane, choose the /lambdasv1 child resource. Create a POST method on the child resource, set the Integration type to Lambda Function, and enter ${stageVariables.function} in Lambda Function. Choose Save.

   Tip

   This step is similar to the step we used to create the GET method. For more information, see Call a Lambda function through an API with a stage variable.

2. From the /Method Execution pane, choose Integration Request. In the Integration Request pane, expand Mapping Templates, and then choose Add mapping template to add a template for the application/json content-type, as shown in the following.

   

   Note

   In a mapping template, a stage variable must be referenced within quotes (as in "$stageVariables.version" or "${stageVariables.version}"). In other places, it must be referenced without quotes (as in ${stageVariables.function}).

3. Deploy the API to available stages.

4. In the Stages navigation pane, choose beta. In beta Stage Editor, verify that the current stage has the most recent deployment. Copy the Invoke URL link, paste it into the URL input field of a REST API client, append /lambdasv1 to that URL, and then submit a POST request to the underlying Lambda function.

   Note

   You will get the following response.

   "Hello, world! (v-beta)"