API Gateway stages and runtime configuration

Automating Deployments on AWS

Dunieski Otano

Amazon Web Services Solutions Architect

Three URLs, one API

• Same checkout API needs dev, staging, and prod
• Each environment hits different downstream resources
• Hardcoding values forces a rebuild per environment
• Stage variables solve this at runtime

What is an API Gateway stage

• A stage is a deployment of an API
• Each stage has its own URL
• Common stages: dev, staging, prod
• One API definition, many stages

Why stages matter for deployments

• Test in dev without affecting prod
• Promote the same API through environments
• Roll back a stage without touching others
• Each stage tracks its own deployment history

Stage variables

• Key-value pairs scoped to one stage
• Reference with ${stageVariables.varName}
• Use them for per-environment config
• No code change needed when values differ

Stage variables in action

• checkout-api -> dev stage: lambdaAlias = dev
• checkout-api -> prod stage: lambdaAlias = prod
• Integration calls payments:${stageVariables.lambdaAlias}
• One API hits two different Lambda aliases

Custom domain names

• Default URL is ugly: abc123.execute-api.us-east-1.amazonaws.com/dev
• Custom domain: api.example.com
  • Requires an ACM certificate for TLS
• Base path mapping ties paths to stages
  • api.example.com/v1 → prod stage

How this ties together

• Stage variables <-> Lambda aliases from video 2.3
• Same idea for ECS task definition versions and DynamoDB table names
• Approved versions per environment, no code changes
• Chapter 3 expands this across services

Let's practice!

Automating Deployments on AWS