API Gateway Caching and Usage Plans

Amazon API Gateway caching stores responses from your backend (e.g., Lambda, HTTP endpoint) so that subsequent identical requests can be served without invoking the backend again. This reduces latency, offloads backend processing, and lowers costs. The cache is an in-memory store located within the API Gateway service, not on your backend.

When a request arrives at API Gateway, the service checks the cache key. The default cache key is the request's path, query string parameters, and headers. If a cached response matches the key and has not expired, API Gateway returns it immediately, bypassing the integration request/response pipeline. If no cache hit occurs, the request proceeds to the backend, and the response is stored in the cache for subsequent requests.

The cache is per stage (e.g., dev, prod). You enable caching on a per-stage basis, not per API. You can also enable caching for specific methods (e.g., GET) or resources. Cache size ranges from 0.5 GB to 237 GB, with pricing based on size. The default TTL is 300 seconds (5 minutes), but you can set it from 0 (no caching) to 3600 seconds (1 hour). Setting TTL to 0 effectively disables caching for that method.

To force a cache refresh, you can:

Important: Cache invalidation via Cache-Control header must be enabled on the method; otherwise, the header is ignored. When you flush the cache, all entries are removed, causing a temporary performance hit until the cache warms up again.

A usage plan defines who can access your API and under what conditions. It consists of: - Throttle: Rate limits (requests per second) and burst limits (maximum requests in a short burst). Default throttle is 10,000 rps per account per region, but can be increased. - Quota: The maximum number of requests a user can make in a day, week, or month. Quota is reset at the start of each period. - API keys: Usage plans are associated with API keys. Each key is a string (e.g., abc123) that clients pass in the x-api-key header. API Gateway validates the key and applies the plan's limits.

When a request includes an API key, API Gateway: 1. Validates the key exists and is active. 2. Checks the associated usage plan. 3. Applies throttle and quota limits. 4. If limits are exceeded, returns 429 Too Many Requests.

Throttling is implemented using a token bucket algorithm. Each API key has a token bucket with a maximum capacity (burst) and refill rate (rate). For example, a rate of 1000 rps and burst of 2000 means the bucket can hold up to 2000 tokens, refilling at 1000 tokens per second. If a request consumes a token and the bucket is empty, the request is throttled.

API keys are not tied to a specific usage plan until you associate them. One key can be associated with multiple usage plans, but only one plan applies per API stage. When you create a usage plan, you specify which API stages it applies to. Then you add API keys to the plan. Clients must send the key in the x-api-key header. If the key is missing or invalid, API Gateway returns 403 Forbidden (not 429).

# Create a usage plan
aws apigateway create-usage-plan \
  --name "BasicPlan" \
  --description "Free tier" \
  --api-stages "[{\"apiId\": \"abc123\", \"stage\": \"prod\"}]" \
  --throttle "{\"rateLimit\": 100, \"burstLimit\": 200}" \
  --quota "{\"limit\": 10000, \"period\": \"DAY\"}"

# Create an API key
aws apigateway create-api-key --name "ClientKey" --enabled

# Associate key with usage plan
aws apigateway create-usage-plan-key \
  --usage-plan-id <plan-id> \
  --key-type API_KEY \
  --key-id <key-id>

Caching and usage plans operate independently. Caching reduces backend load, but usage plans control client access. A cached response is served without checking the usage plan again—the plan is only checked on the initial request. This means a client could exceed its quota via cached responses? No, because the quota is counted per request, even cached ones? Actually, API Gateway counts every request against the quota, regardless of cache hit. So caching does not bypass usage plan limits. However, throttling is applied before caching: if a request is throttled, it never reaches the cache check.

| Feature | Default | Maximum | |---------|---------|---------| | Cache TTL | 300 s | 3600 s | | Cache size | 0.5 GB | 237 GB | | Throttle rate (account) | 10,000 rps | Can increase | | Burst (account) | 5,000 | Can increase | | Quota | None | Unlimited |

API Gateway caching and usage plans are essential for building production-ready APIs. Caching reduces latency and backend load, while usage plans enforce access policies and prevent abuse. On the DVA-C02 exam, you must know the default values, how caching interacts with throttling, and how to configure usage plans with API keys. Practice with the AWS CLI and console to solidify these concepts.

A large e-commerce company exposes a REST API for product details (GET /products/{id}). The product data changes infrequently (once per day). To reduce load on the backend DynamoDB table and improve response times, they enable API Gateway caching with a TTL of 3600 seconds (1 hour). They also create usage plans for different client tiers: a free tier with 1000 requests per day and 10 rps throttle, and a premium tier with 100,000 requests per day and 100 rps throttle. Each client gets an API key. The caching reduces backend calls by 90%, and usage plans prevent abuse. A common issue is that when product prices are updated, the cache serves stale data for up to an hour. To mitigate, they implement a cache invalidation endpoint (POST /products/{id}/invalidate) that flushes the cache for that specific product using the InvalidateCache API. They also set up CloudWatch alarms to monitor throttle count; if it spikes, they investigate potential DDoS attacks.

A SaaS provider offers an analytics API where each customer has a unique API key. They use usage plans to enforce per-customer quotas (e.g., 10,000 requests per month). They also enable caching for expensive aggregation queries that return the same results for all customers (e.g., total sales). However, they must ensure that cached responses are not served to the wrong customer. They solve this by using a cache key that includes the API key (via a custom header or the x-api-key header). This way, each customer's cached data is isolated. They set a TTL of 300 seconds. Misconfiguration: initially they did not include the API key in the cache key, causing cross-tenant data leaks. They fixed it by enabling cache key parameters (query strings, headers) in the method request. They also set up usage plan alerts to notify when a customer approaches their quota.

A mobile app uses API Gateway to serve user-specific data (e.g., profile, notifications). Caching is dangerous here because data is user-specific. Instead, they disable caching for these endpoints. For public content (e.g., news feed), they enable caching with a TTL of 60 seconds. They use usage plans to limit free users to 100 requests per day, while premium users have unlimited access. They also implement API key rotation every 90 days to prevent key leakage. A common problem is that when a user upgrades from free to premium, their old API key is still associated with the free plan. They must create a new key or update the usage plan association. They automate this via AWS SDK in their user management system.