On this page
API gateway caching stores responses from an API’s backend so that repeated requests can be served without running the same backend operation every time. It can reduce response times, lower backend workload, and improve an application’s ability to handle repeated requests.
When a client requests data through an API gateway, the gateway can check its cache before forwarding the request to the backend. If a valid cached response exists, it returns that response. If no suitable entry exists, the request goes to the backend, and the response may be stored for future requests.
This guide explains how API Gateway caching works, how to choose cache keys and expiration times, how to configure AWS API Gateway caching, and how to troubleshoot stale responses and cache misses.
What Is API Gateway Caching?
API Gateway caching is a performance technique that temporarily stores API responses at the gateway layer. Instead of sending every request to an application server or database, the gateway can reuse a previously generated response when a matching request arrives.
For example, imagine an application that provides product category information. Hundreds of users may request the same category data throughout the day. If the information does not change frequently, the gateway can cache the response and serve it to subsequent users until the cached entry expires or is invalidated.
Without caching, each request may require the backend to perform the same database queries and response processing. With caching, repeated requests can avoid some of that work.
The benefit depends on the endpoint, request patterns, response size, and how frequently the underlying data changes. Caching is most useful when responses can safely be reused. It is less suitable for information that must always reflect the latest state or differs between users.
How Does API Gateway Caching Work?
API gateway caching generally follows a simple process.
- A client sends a request to the API gateway.
- The gateway identifies the request using its configured cache key.
- If a valid cached response exists, the gateway returns it.
- If there is no usable entry, the gateway forwards the request to the backend.
- The backend processes the request and returns a response.
- If the response is eligible for caching, the gateway stores it for future requests.
The two main outcomes are a cache hit and a cache miss.
A cache hit occurs when the gateway finds a reusable response. A cache miss occurs when the gateway needs to obtain a response from the backend instead.
<box gap={2} border radius="lg" padding={3}> <box background="surface-secondary" radius="md" padding={3} align="center"> **Client request**<text color="secondary" size="sm">Requests an API resource</text></box> <box align="center"> <icon name="arrow-down" size="xl" color="secondary" /> </box> <box border radius="md" padding={3} align="center"> **API gateway cache**<text color="secondary" size="sm">Looks up the request's cache key</text></box> <grid columns={2} gap={2}> <grid-item> <box background="surface" border radius="md" padding={2} align="center" gap={1}> <icon name="check-circle" color="success" size="lg" /> **Cache hit** <code> <text color="secondary" size="sm" textAlign="center">Return the cached response</text>
</box>
</grid-item>
<grid-item>
<box background="surface" border radius="md" padding={2} align="center" gap={1}>
<icon name="refresh-cw" size="lg" />
**Cache miss**
<text color="secondary" size="sm" textAlign="center">Forward request to backend</text>
</box>
</grid-item></code></grid> <text color=”secondary” size=”sm”>On a cache miss, an eligible response may be stored and reused by later matching requests.</text> </box>
The gateway must identify which requests can safely share a response. If two requests require different data but use the same cache key, the gateway could return incorrect information. Cache-key design is therefore just as important as enabling caching.
Why Should You Use API Gateway Caching?
Caching can improve API performance, but its value depends on how your application handles requests and how often its data changes.
Reduce Response Latency
When a response is already cached, the gateway can avoid waiting for the backend to perform the full operation. This can be particularly helpful for endpoints that repeatedly return the same reference data, product information, or public content.
The actual improvement depends on network latency, cache location, response size, and the work the backend would otherwise perform.
Reduce Backend Workload
Repeated API requests can consume application resources and trigger database queries. Caching eligible responses reduces the number of requests that reach the backend, leaving more capacity for requests that genuinely require processing.
Improve Performance During Repeated Traffic
Applications often receive bursts of requests for the same resources. A cache can serve matching requests without repeatedly running the same backend operations.
However, caching does not remove every performance bottleneck. Requests with unique cache keys, expired entries, or uncached endpoints still reach the backend.
Manage Infrastructure Costs
Reducing backend requests may lower resource consumption in some architectures. Whether this translates into overall savings depends on the cache service’s cost, the backend’s pricing model, and the number of requests that can actually be served from the cache.
For managed services such as Amazon API Gateway, include cache capacity and hourly charges in your cost calculations.
Which API Responses Should You Cache?
Not every endpoint benefits equally from caching. Start with responses that are frequently requested, relatively stable, and safe to reuse.
| API response type | Caching suitability | What to consider |
|---|---|---|
| Public product categories | Often suitable | Set an expiration time that reflects how frequently categories change |
| Public configuration data | Often suitable | Invalidate or refresh the cache when settings change |
| Product details | Depends on the data | Consider price, stock, and other frequently changing fields |
| Search results | Depends on request patterns | Include relevant search parameters in the cache key |
| User profile information | Requires careful design | Separate entries by authenticated identity and relevant permissions, or avoid shared caching |
| Account balances and payment status | Usually unsuitable for shared response caching | These values may require fresh, user-specific data |
| Frequently changing inventory | Use cautiously | Short expiration times may be necessary, and some operations should bypass caching |
These are general guidelines rather than universal rules. The correct choice depends on the application’s consistency requirements and the sensitivity of the response.
What Is a Cache Key in API Gateway Caching?
A cache key determines which requests can use the same cached response. Depending on the gateway, a key may include request parameters such as the resource path, query string, or selected headers.
Suppose an API provides product information:
GET /products?category=hosting
GET /products?category=securityIf the category parameter is part of the cache key, the gateway can store separate responses for hosting and security products.
If the gateway ignores the category parameter, both requests might map to the same cache entry. That can result in the wrong products being returned.
The same issue applies to language, currency, pagination, tenant identity, and other parameters that affect the response.
Choose Cache Keys Carefully
Before enabling caching, identify every request value that can change the response.
For example:
| Request parameter | Include in the key when |
|---|---|
| Resource path | Different paths return different data |
| Query string | Filters, search terms, sorting, or pagination change the result |
| Language header | The API returns translated content |
| Currency parameter | The response includes currency-dependent prices |
| Tenant or user identity | Responses are specific to a customer or account and the caching system supports safe isolation |
Do not automatically add every header or parameter. Extra key variations create more cache entries and may reduce the hit rate. Include the values needed to distinguish genuinely different responses.
For sensitive, authenticated endpoints, verify the gateway’s authorization and cache behavior carefully. Never assume that a cache key automatically makes a shared cache safe for private data.
How to Configure AWS API Gateway Caching
Amazon API Gateway provides response caching for REST APIs. The configuration below focuses on that API type because the available caching features and settings differ between API Gateway offerings.
AWS API Gateway caching uses a cache cluster associated with an API stage. You can enable caching for eligible methods, choose a time-to-live value, and configure cache keys for request parameters.
Step 1: Open Your API Stage
Sign in to the AWS Management Console and open API Gateway.
- Select the relevant REST API.
- Open Stages.
- Select the stage you want to configure, such as
prod. - Open the stage’s cache settings.
Use a non-production stage first if you need to validate the behavior before applying changes to a live API.
Step 2: Provision the Cache
In the stage settings, enable the API cache and choose an appropriate cache capacity.
Provisioning creates a dedicated cache instance for the stage. AWS notes that creating or changing cache capacity can take several minutes and that changing capacity can replace the existing cache instance and remove cached data.
Cache capacity affects available CPU, memory, and network bandwidth. A larger cache may help some workloads but also costs more, so choose capacity based on testing rather than assumptions.
Step 3: Enable Method-Level Caching
Enable the default method-level caching setting if you want caching applied to eligible methods across the stage. You can also configure individual method overrides.
For REST APIs, enabling the stage’s default method-level caching setting enables caching for GET methods by default, subject to existing method-level overrides.
Do not enable caching indiscriminately for methods that create, update, or delete data. Such operations often require fresh backend processing and can have side effects.
Step 4: Set the Time to Live
The time to live (TTL) determines how long a cached response can be reused before it expires.
For Amazon API Gateway REST API caching, the documented default TTL is 300 seconds, and the maximum is 3,600 seconds. Setting TTL to 0 disables caching for the relevant setting. Confirm the current service documentation before applying these values to your configuration.
Choose a TTL that reflects how often the underlying information changes. Public category data may tolerate a longer interval than product availability or other frequently changing information.
Step 5: Configure Cache Keys
If the response depends on request parameters, configure the relevant method or integration parameters as cache keys.
For example, if an endpoint returns different products based on a query string, include that parameter in the key. AWS API Gateway supports cache keys based on configured request parameters, including query strings, paths, and headers.
Check that the key distinguishes every response variation that matters. A correct TTL cannot fix a cache key that combines unrelated requests.
Step 6: Deploy and Test
After saving your configuration, deploy the API changes if required by your workflow and test the endpoint with repeated requests.
Compare the first request with later requests that use the same key. Also test requests with different parameters to confirm that they return the correct data.
Use Amazon CloudWatch metrics such as CacheHitCount and CacheMissCount to monitor the cache. AWS recommends load testing with traffic that reflects real usage, including repeated requests and unique requests that populate new cache entries.
For the complete procedure, consult the official AWS API Gateway caching documentation.
How to Choose the Right Cache TTL
TTL is one of the most important decisions in API Gateway caching. A longer TTL can increase the chance of cache hits, but it can also keep outdated data available for longer. A shorter TTL makes cached information expire sooner but may increase backend requests.
Use the data’s actual update pattern to guide the setting.
| Data type | Example starting point | Reason |
|---|---|---|
| Stable public reference data | Several minutes or longer | Changes infrequently |
| Public product descriptions | A few minutes | Updates may need to appear reasonably quickly |
| Product prices or availability | Short TTL or selective caching | Information can change frequently |
| User-specific account data | Avoid shared caching unless isolation is proven safe | Responses may be sensitive or identity-dependent |
| Payment or transaction status | Usually fetch fresh data | Incorrectly reused responses can have serious consequences |
These are starting points for evaluation, not universal recommended TTLs. Measure your application’s update frequency and consistency requirements before settling on a value.
Also consider what happens when a cache entry expires. If many entries expire at the same time, a burst of requests may reach the backend together. Load testing can help reveal whether the backend handles this pattern safely.
How to Monitor API Gateway Cache Performance
After enabling caching, measure whether it is actually reducing backend requests and improving response times.
For AWS API Gateway REST APIs, Amazon CloudWatch provides cache-related metrics, including CacheHitCount and CacheMissCount.
A high cache hit count can indicate that requests are reusing stored responses. A high miss count may indicate that requests are unique, entries are expiring frequently, or cache keys are too specific. A low hit rate is not automatically a failure if most requests require fresh or user-specific data.
Monitor these metrics alongside:
- API latency and backend integration latency.
- HTTP error rates, including 4xx and 5xx responses.
- Backend CPU, memory, and database workload.
- Request volume and the variety of cache keys.
- Cache capacity and cost.
Compare the results before and after enabling caching. If backend workload falls but users still experience slow responses, the remaining delay may be elsewhere in the request path.
Do not use a single response header as definitive proof that an API Gateway cache served a response. Follow the service’s documented metrics and testing guidance.
Common API Gateway Caching Problems and Fixes
Caching problems often come from incorrect cache keys, inappropriate TTL settings, or assumptions about which requests should reuse responses.
| Problem | Possible cause | What to check |
|---|---|---|
| API keeps returning old data | TTL is too long or an entry has not been invalidated | Review TTL and cache invalidation behavior |
| Cache hit rate is low | Requests have many unique keys or entries expire frequently | Inspect query parameters and key design |
| Different requests return the same response | A relevant parameter is missing from the cache key | Add the parameter or disable caching for that method |
| Cache does not appear active | The stage cache is not provisioned or method caching is disabled | Check stage and method-level settings |
| Backend load remains high | Requests are unique, uncached, or missing the cache | Review hit and miss metrics |
| Cache changes cause unexpected behavior | Method overrides or deployment settings differ | Inspect the individual method configuration |
Fix Stale API Responses
If clients receive outdated information, review the TTL and determine whether the data should be cached at all.
For Amazon API Gateway REST APIs, you can flush a stage’s cache when you need to clear its cached entries. This forces subsequent requests to obtain responses from the integration endpoint until the cache is populated again, which can temporarily increase backend load and latency.
If a response must always reflect the latest state, disabling caching for that method may be safer than relying on frequent manual invalidation.
Fix Cache Key Problems
When different requests produce the same cached response, compare the requests and identify which values change the result.
Include those values in the cache key if the gateway supports the required configuration. If the response depends on sensitive identity or authorization information, do not proceed until you have verified that the cache safely isolates users and permissions.
Fix Low Cache Hit Rates
Review how often requests repeat with the same key. If nearly every request contains a unique identifier or search term, caching may provide limited benefit.
You can also check whether the TTL is too short for the data’s update pattern. Avoid extending it solely to increase the hit rate if doing so would make the data too stale.
API Gateway Caching Best Practices
A reliable caching setup needs more than an enabled cache. Apply these practices to keep performance improvements from creating data consistency or security problems.
Cache Only Responses That Can Be Reused
Start with endpoints that return stable, repeatable data. Be cautious with account details, transaction status, and responses that depend on authorization.
Use Accurate Cache Keys
Include the request parameters that change the response. Test different query values, languages, and identities where relevant to confirm that requests cannot receive another user’s data.
Set TTL Based on Data Freshness
Use the shortest TTL that meets your performance goals without unnecessarily increasing backend requests. Revisit the value whenever the data’s update pattern changes.
Control Cache Invalidation
Define how the application handles updates that must become visible before an entry expires. Where supported, use deliberate invalidation or cache flushing, and account for the temporary increase in backend requests.
Protect Sensitive Cached Data
If cached responses may contain sensitive information, review the gateway’s encryption options, authorization model, and cache-key design. AWS API Gateway REST API caching supports an option to encrypt cached data. Encryption does not replace access controls or correct cache isolation.
Measure Before Increasing Capacity
Do not assume a larger cache will automatically improve performance. Use realistic load tests and monitor latency, errors, cache hits, and cache misses before changing capacity.
Frequently Asked Questions
What is the default TTL for AWS API Gateway caching?
For Amazon API Gateway REST API caching, AWS documents a default TTL of 300 seconds and a maximum of 3,600 seconds. Check the current official documentation when configuring a production API, because service capabilities and defaults may change.
Does API gateway caching reduce backend costs?
It can reduce backend requests and resource usage, which may lower costs in some architectures. The overall savings depend on cache utilization, backend pricing, cache capacity charges, and the cost of the surrounding infrastructure.
Should all API endpoints be cached?
No. Caching is most useful for repeatable responses that can safely be reused. Endpoints that return sensitive, personalized, rapidly changing, or transaction-critical data need more careful handling and may be better left uncached.
Conclusion
API gateway caching can improve API responsiveness and reduce repeated backend work when requests return reusable data. The key is to choose suitable endpoints, design accurate cache keys, and set a TTL that balances performance with data freshness.
For AWS API Gateway REST APIs, configure caching at the stage and method levels, test the behavior with different requests, and monitor cache hits and misses through CloudWatch. Review security and invalidation requirements before caching sensitive or frequently changing responses.
A well-planned cache can make an API more efficient. A poorly configured one can return stale or incorrect data, so measure the results and validate the behavior before relying on it in production.
