Testing Applications with Amazon API Gateway Endpoints

This guide covers how to leverage Amazon API Gateway Stages and Stage Variables to create distinct development, testing, and production environments. Mastering these tools allows for safe iteration without affecting live users.

Learning Objectives

By the end of this guide, you should be able to:

Define the role of an API Stage as a logical snapshot of an API's configuration.
Configure Stage Variables to route traffic to specific backend resources (e.g., Lambda aliases).
Analyze the impact of Throttling and Caching on different development endpoints.
Execute manual cache invalidation using IAM policies and request headers.

Key Terms & Glossary

API Stage: A logical reference to a lifecycle state of your API (e.g., dev, prod). It is a snapshot of the API that is made live through a deployment.
Stage Variable: A name-value pair defined at the stage level that acts as a configuration parameter for API resources and methods.
Invoke URL: The specific HTTP endpoint used to call a stage, formatted as https://{api-id}.execute-api.{region}.amazonaws.com/{stage-name}/.
Throttling: The process of limiting the rate of requests to protect backend services. API Gateway returns a 429 Too Many Requests error when limits are exceeded.
TTL (Time-to-Live): The duration (in seconds) that a response remains in the API Gateway cache. Default is 300s.

The "Big Idea"

The core philosophy of testing with development endpoints is the Separation of Concerns. Instead of creating entirely separate API Gateways for every environment, you use Stages to create isolated "logical" environments within the same API. This ensures that the configuration you test in dev is the exact same structure you promote to prod, reducing "it worked on my machine" deployment errors.

Formula / Concept Box

Concept	Rule / Description	Key Constraint
Invoke URL Structure	`https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/{resource}`	`{stage}` is required in the path
Throttling (RPS)	Regional steady-state limit for all APIs in an account.	Can be overridden per stage
Cache Invalidation	Client header: `Cache-Control: max-age=0`	Requires `execute-api:InvalidateCache` permission
Cache TTL	Default: 300s, Min: 0s, Max: 3600s	Configured at the Stage level

Hierarchical Outline

API Deployment Lifecycle
- Resources & Methods: Defined but not accessible until deployed.
- Deployments: Immutable snapshots of the API configuration.
- Stages: Pointers to specific deployments (e.g., v1, v2, beta).
Dynamic Routing with Stage Variables
- Backend Integration: Using ${stageVariables.variableName} in Lambda function names or HTTP URIs.
- Versioning: Mapping prod stage to a "Stable" Lambda alias and dev to $LATEST.
Endpoint Management
- Throttling: Per-stage overrides for Requests Per Second (RPS) and Burst limits.
- Caching: Enabling responses to be stored at the edge to reduce backend load.

Visual Anchors

Request Routing via Stage Variables

Loading Diagram...

API Gateway URL Anatomy

\begin{tikzpicture}[node distance=1cm, every node/.style={font=\small}] \node (url) {\texttt{https://nuowwpf0x4.execute-api.us-east-1.amazonaws.com/dev/recommendations}};

code

\draw[<-] (0.5,0.2) -- ++(0,0.5) node[above] {API ID};
\draw[<-] (3.5,0.2) -- ++(0,0.8) node[above] {Service/Region};
\draw[<-] (5.8,-0.2) -- ++(0,-0.5) node[below] {\textbf{Stage Name}};
\draw[<-] (7.5,-0.2) -- ++(0,-0.8) node[below] {Resource Path};

\end{tikzpicture}

Definition-Example Pairs

Stage Variable Implementation
- Definition: Using placeholders in the API configuration that are resolved at runtime based on the calling stage.
- Example: Setting an integration URI to http://${stageVariables.url}/login. In the dev stage, url is dev.example.com, while in prod it is api.example.com.
Throttling Override
- Definition: Adjusting the request rate limits for a specific stage to be lower or higher than the account default.
- Example: Setting the dev stage to 10 RPS to prevent runaway testing scripts from consuming the account-wide quota, while keeping prod at 5000 RPS.

Worked Examples

Scenario: Configuring a Development Endpoint for Lambda

Requirement: Create a dev stage that calls the latest version of a Lambda function and a prod stage that calls a stable alias named v1.
Step 1 (Lambda): Create a Lambda function and a version/alias. Name the alias v1.
Step 2 (API Gateway): In the Lambda Integration, set the function name to MyFunctionName:${stageVariables.lambdaAlias}.

[!IMPORTANT] You must grant API Gateway permission to invoke the Lambda function using the CLI, as the console might not recognize the variable syntax for permissions.
Step 3 (Stages):
- Create a stage named dev and add a variable lambdaAlias with the value DEV (or $LATEST).
- Create a stage named prod and add a variable lambdaAlias with the value v1.
Validation: Invoking the URL with /dev/ will now execute the experimental code, while /prod/ remains on the stable code.

Checkpoint Questions

Which HTTP status code is returned when a client exceeds the throttling limits configured on an API Stage?
- Answer: 429 Too Many Requests.
True or False: Enabling API Gateway Caching is recommended for development stages to save costs.
- Answer: False. Caching usually increases costs and can hide bugs during development by returning stale data.
A developer wants to bypass the cache for a single request to test the latest backend changes. What header and value should they send?
- Answer: Cache-Control: max-age=0 (Requires appropriate IAM permissions).
What happens if you change a Resource or Method in API Gateway but do not create a new Deployment?
- Answer: The changes will not be reflected in any Stage. You must deploy the API to a stage to make the changes live.

Muddy Points & Cross-Refs

Permissions: One common "muddy point" is the Lambda Permission. When using Stage Variables in Lambda integrations, you must manually add the lambda:InvokeFunction permission for each stage/alias because API Gateway cannot determine which function to authorize during the setup phase.
Deployment Rollbacks: Remember that a Stage is just a pointer. To "roll back," you simply point the Stage back to a previous Deployment ID.
Further Study: See Unit 2: Security for how to protect these endpoints using IAM or Cognito Authorizers.