API Gateway stages and runtime configuration
1. API Gateway stages and runtime configuration
Welcome back! In this video, you'll configure API Gateway stages, use stage variables for per-environment values, and pick the right approach for runtime configuration. Let's get started.2. Three URLs, one API
Take the same checkout API you've been working with. You need a dev URL for testing, a staging URL for QA, and a prod URL for customers. Each environment needs to call different downstream resources: a different Lambda alias, a different DynamoDB table, a different backend host. Hardcoding those values means you rebuild the API for every environment, breaking the build-once-deploy-many promise. Stages and stage variables are how API Gateway solves this.3. What is an API Gateway stage
A stage is simply a deployment of your API at a point in time, and each one gets its own URL, like the dev and prod URLs shown here. Those dev, staging, and prod environments from a moment ago are really just three stages of one API definition. The code paths stay identical; only the runtime configuration changes per stage. That is how one API serves every environment cleanly.4. Why stages matter for deployments
Stages are how API Gateway supports a real release pipeline. Dev is where you break things safely, staging is where you validate, and prod is where your customers live, all from one API definition promoted forward. Because each stage keeps its own deployment history, you can roll a single stage back to a previous version without disturbing the others. Stages are the API Gateway equivalent of environments: same code, different runtime context.5. Stage variables
Stage variables are key-value pairs you set on a single stage. You reference them with the dollar-curly placeholder, stageVariables dot the variable name, like in shell. The classic use case is per-environment config: a Lambda alias name, a backend host, a feature flag. You can deploy the same API definition to dev and prod, but stage variables make each one point to different downstream resources. No code change required to switch environments.6. Stage variables in action
Take the same checkout-api and payments Lambda from earlier. The dev stage sets a stage variable, lambdaAlias, to dev, and the prod stage sets the same variable to prod. The integration then invokes the payments function using that variable as the alias suffix, where the colon selects a Lambda alias. So at runtime the dev stage calls payments:dev and the prod stage calls payments:prod. Same API, two different aliases, all controlled by one stage variable.7. Custom domain names
The default API Gateway URL works but isn't pretty. For production, you want a custom domain like api dot example dot com. After verifying the domain with an ACM certificate, you set up a base path mapping. That mapping ties a URL path to a stage. For instance, api.example.com slash v1 routes to the prod stage. You can have multiple base paths pointing to different stages or even different APIs, all under the same domain.8. How this ties together
Stage variables are the API Gateway side of a bigger pattern. They pair naturally with the Lambda aliases you saw in video 2.3: the alias holds the approved version per environment, the stage variable selects which alias to call. The same idea applies to ECS task definition revisions, which are ECS' equivalent of an alias, and to DynamoDB table names. You get per-environment configuration without changing code or rebuilding artifacts. Chapter 3 expands this idea across all the services that need approved versions.9. Let's practice!
Time to configure some stage variables. Time to practice!Create Your Free Account
or
By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.