Set up Stage Variable for API Deployment
Stage variables are name-value pairs that you can define as configuration attributes associated with a deployment stage of an API. They act like environment variables and can be used in your API setup and mapping templates.
For example, you can define a stage variable in a stage configuration, and then set its value as the URL string of an HTTP integration for a method in your API. Later, you can reference the URL string using the associated stage variable name from the API setup. This way, you can use the same API setup with a different endpoint at each stage by resetting the stage variable value to the corresponding URLs. You can also access stage variables in the mapping templates, or pass configuration parameters to your AWS Lambda or HTTP backend.
For more information about mapping templates, see API Gateway Mapping Template Reference.
Use Cases
With deployment stages in API Gateway, you can manage multiple release stages for
each API, such
as alpha, beta, and production. Using stage variables you can configure an API deployment
stage to interact with different backend endpoints. For example, your API can pass
a GET
request as an HTTP proxy to the backend web host (for example,
http://example.com). In this case, the backend web host is configured in a
stage variable so that when developers call your production endpoint, API Gateway
calls example.com.
When you call your beta endpoint, API Gateway uses the value configured in the stage
variable for
the beta stage, and calls a different web host (for example, beta.example.com).
Similarly, stage variables can be used to specify a different AWS Lambda function
name for each
stage in your API.
You can also use stage variables to pass configuration parameters to a Lambda function through your mapping templates. For example, you may want to re-use the same Lambda function for multiple stages in your API, but the function should read data from a different Amazon DynamoDB table depending on which stage is being called. In the mapping templates that generate the request for the Lambda function, you can use stage variables to pass the table name to Lambda.
Examples
To use a stage variable to customize the HTTP integration endpoint, you must first
configure a stage variable of a specified name, e.g., url, and then assign it a value, e.g.,
example.com. Next, from your method configuration, set up an HTTP proxy
integration, and instead of entering the endpoint's URL, you can tell API Gateway
to use the stage variable
value, http://${stageVariables.url}. This value tells API Gateway to
substitute your stage variable ${} at runtime, depending on which stage your API
is running. You can reference stage variables in a similar way to specify a Lambda
function
name, an AWS Service Proxy path, or an AWS role ARN in the credentials field.
When specifying a Lambda function name as a stage variable value, you must configure the permissions on the Lambda function manually. You can use the AWS Command Line Interface to do this.
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
The following example assigns API Gateway permission to invoke a
Lambda function named helloWorld hosted in the US West (Oregon) region of an AWS
account on behalf of the API method.
arn arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello
Here is the same command using the AWS CLI.
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:123123123123:function:helloWorld --source-arn arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
