API Gateway Stage Variables
You'll learn how to use stage variables to keep your API configurations flexible across multiple environments without duplicating resources.
What Are Stage Variables?
Stage variables are key-value pairs you can define for each deployment stage of your API Gateway. Think of them like environment-specific configuration settings that let you change backend endpoints, HTTP headers, or other settings without modifying your API definition.
The coffee shop analogy: Imagine a coffee shop franchise with three locations (dev, staging, prod). Each location follows the same menu and processes, but calls different suppliers for ingredients. Stage variables are like having the supplier phone numbers written on a whiteboard at each location—same workflow, different contacts.
Why Use Stage Variables?
Without stage variables, you'd need separate API definitions for development, staging, and production. That means three times the maintenance work. Stage variables let you:
- Point to different backend endpoints per stage
- Configure stage-specific throttling limits
- Pass environment-specific values to your integrations
- Reference different function versions or aliases
Common Use Cases
When deploying to different stages, you might use stage variables to:
- Reference
${stageVariables.backendUrl}to route dev traffic todev-api.example.comand prod traffic toapi.example.com - Invoke different function aliases:
myFunction:${stageVariables.lambdaAlias} - Set stage-specific API keys or authentication parameters
Stage variables appear in your integration requests, mapping templates, and can even be used in custom domain configurations.
Key Takeaway: Stage variables parameterize your API Gateway configuration, letting you deploy the same API definition to multiple environments (dev, staging, prod) while automatically connecting to the appropriate backends for each stage.