AWS API Gateway: Stages, Variables, and Custom Domains

Learning Objectives

After studying this guide, you should be able to:

• Explain the relationship between Deployments and Stages.
• Configure and use Stage Variables to parameterize backend integrations.
• Describe the purpose and setup of Custom Domain Names in API Gateway.
• Differentiate between Dev, Test, and Prod environments within a single API.
• Understand how to implement Throttling and Canary Deployments at the stage level.

Key Terms & Glossary

• Stage: A logical reference to a lifecycle state of your API (e.g., prod, beta). It points to a specific deployment snapshot.
• Deployment: A point-in-time snapshot of your API resources and methods. You must "deploy" to make changes live.
• Stage Variable: A name-value pair that acts like an environment variable for your API stage.
• Invoke URL: The default HTTPS endpoint generated by AWS (e.g., https://{api-id}.execute-api.{region}.amazonaws.com/{stage}).
• Custom Domain Name: A user-friendly URL (e.g., api.example.com) that maps to your API Gateway stages.
• Base Path Mapping: A configuration that links a custom domain name and optional path to a specific API and stage.

The "Big Idea"

In modern cloud development, you shouldn't hardcode endpoints. API Gateway Stages allow you to maintain multiple versions of your API (Development, QA, Production) simultaneously without changing your code structure. By using Stage Variables, your API becomes a dynamic template: the same API definition can point to a "Dev" Lambda function in one stage and a "Prod" Lambda function in another, simply by swapping a variable value.

Formula / Concept Box

Hierarchical Outline

• I. API Deployments and Stages
  • Snapshot Logic: Changes made in the console are not live until a Deployment is created.
  • Stage Association: A stage is a "pointer" to a specific deployment ID.
  • Lifecycle Management: Facilitates gradual rollouts and A/B testing via Canary Deployments.
• II. Stage Variables
  • Purpose: Externalize configuration (URLs, ARNs, feature flags).
  • Supported Integrations: HTTP Endpoints, Lambda Function ARNs, and Mapping Templates.
  • Benefits: Environment isolation without duplicating API resources.
• III. Custom Domain Names
  • Prerequisites: Requires an SSL/TLS certificate from AWS Certificate Manager (ACM).
  • Types:
    • Edge-optimized: Routed via CloudFront (global).
    • Regional: Deployed in the specific AWS region.
  • Mapping: Use Base Path Mappings to route api.com/v1 to Stage A and api.com/v2 to Stage B.

Visual Anchors

The Deployment Workflow

Custom Domain Mapping

\begin{tikzpicture}[node distance=2cm, every node/.style={draw, rectangle, align=center, rounded corners}] \node (domain) [fill=blue!10] {Custom Domain$api.example.com)}; \node (mapping1) [right=of domain, yshift=1cm] {Base Path: /v1\Map to API-A, Stage: Prod}; \node (mapping2) [right=of domain, yshift=-1cm] {Base Path: /dev\Map to API-A, Stage: Dev}; \draw[->, thick] (domain.east) -- (mapping1.west); \draw[->, thick] (domain.east) -- (mapping2.west); \end{tikzpicture}

Definition-Example Pairs

• Stage Variable: A key-value pair configured at the stage level.
  • Example: Setting a variable env to prod. In your HTTP integration, you use http://${stageVariables.env}.example.com/data to dynamically route requests.
• Canary Deployment: A feature where a small percentage of traffic is shifted to a new "canary" deployment for testing.
  • Example: Routing 10% of users to a new API version to monitor for errors before a full 100% rollout.
• Throttling: Limits on the rate of requests.
  • Example: Setting a prod stage to 10,000 requests per second (RPS) while limiting the dev stage to 100 RPS to save backend costs.

Worked Examples

Example 1: Dynamic Lambda Routing

Scenario: You have two Lambda aliases, PROD and DEV. You want your API to call the correct alias based on the stage.

1. Define Stage Variables:
   • In the prod stage, create a variable functionAlias = PROD.
   • In the dev stage, create a variable functionAlias = DEV.
2. Configure Integration:
   • In the Lambda integration field, enter: arn:aws:lambda:us-east-1:123456789012:function:MyProcessor:${stageVariables.functionAlias}.
3. Permission:
   • Ensure you grant API Gateway permission to invoke the Lambda function using a wildcard for the alias in the resource-based policy.

Example 2: Setting up a Custom Domain

Scenario: Making your API accessible at api.mycompany.com.

1. Certificate: Request a certificate for api.mycompany.com in ACM (must be in us-east-1 for edge-optimized).
2. Create Custom Domain: In API Gateway console, go to "Custom Domain Names" and create one using the ACM certificate.
3. Base Path Mapping: Map the empty path (none) to your API MySystem and stage prod.
4. DNS: In Route 53, create an A-Alias record pointing api.mycompany.com to the API Gateway domain name provided in the console.

Checkpoint Questions

1. What is the difference between a Deployment and a Stage in API Gateway?
2. Which HTTP status code is returned when a client exceeds the throttling limits configured on a stage?
3. How do you access a stage variable named dbEndpoint in a mapping template?
4. Why must you use AWS Certificate Manager (ACM) when setting up a Custom Domain Name?
5. Can you have different throttling settings for different stages of the same API? Explain.

[!TIP] Remember: When you change an API's resources or methods, the changes are not automatically reflected in the Stage. You must create a new Deployment and update the Stage to point to it!

[!WARNING] If you use stage variables in a Lambda integration, the AWS Console cannot automatically add the lambda:InvokeFunction permission for you. You must add this permission manually via the AWS CLI or CloudFormation.