| name | managing-api-cache |
| description | Implement intelligent API response caching with Redis, Memcached, and CDN integration.
Use when optimizing API performance with caching.
Trigger with phrases like "add caching", "optimize API performance", or "implement cache layer".
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash(api:cache-*) |
| version | 1.0.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| compatible-with | claude-code, codex, openclaw |
| tags | ["api","redis","performance"] |
Managing API Cache
Overview
Implement intelligent API response caching using Redis, Memcached, or in-memory stores with cache key generation, TTL management, cache invalidation strategies, and HTTP cache headers. Support read-through, write-through, and cache-aside patterns with tag-based invalidation for related resources and stale-while-revalidate behavior.
Prerequisites
- Redis 6+ or Memcached for distributed caching (required for multi-instance deployments)
- Cache client library:
ioredis (Node.js), redis-py (Python), or Lettuce (Java)
- CDN with cache control support for edge caching (CloudFront, Cloudflare, Fastly) -- optional
- Monitoring for cache hit/miss ratios and eviction rates
- Understanding of data freshness requirements per endpoint
Instructions
- Analyze endpoint characteristics using Read and Grep to classify endpoints by cacheability: fully cacheable (static data), conditionally cacheable (user-specific data), and never cacheable (mutations, real-time data).
- Implement cache key generation middleware that creates deterministic keys from method, path, query parameters (sorted), and relevant headers (Accept, Authorization hash for user-specific caches).
- Build a cache-aside middleware that checks the cache before executing the handler, returning cached responses with
X-Cache: HIT header, or executing the handler, caching the result, and returning with X-Cache: MISS.
- Configure TTL per endpoint category: long TTL (1 hour) for reference data, medium TTL (5 minutes) for frequently changing lists, short TTL (30 seconds) for near-real-time data.
- Implement cache invalidation on mutations: when a POST/PUT/DELETE modifies a resource, invalidate all cached responses containing that resource using tag-based invalidation.
- Add
Cache-Control, ETag, and Last-Modified response headers for HTTP-level caching, enabling CDN and browser cache participation.
- Implement stale-while-revalidate behavior: serve stale cached responses immediately while asynchronously refreshing the cache in the background, reducing perceived latency.
- Add cache warming for critical endpoints: pre-populate cache entries on application startup or schedule for frequently accessed resources.
- Write tests verifying cache hits, misses, invalidation correctness, TTL expiration, and stale-while-revalidate behavior.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/src/middleware/cache.js - Cache-aside middleware with hit/miss tracking${CLAUDE_SKILL_DIR}/src/cache/key-generator.js - Deterministic cache key generation${CLAUDE_SKILL_DIR}/src/cache/invalidator.js - Tag-based cache invalidation on mutations${CLAUDE_SKILL_DIR}/src/cache/store.js - Redis/Memcached cache store abstraction${CLAUDE_SKILL_DIR}/src/config/cache-policies.js - Per-endpoint TTL and caching policy configuration${CLAUDE_SKILL_DIR}/tests/cache/ - Cache behavior verification tests
Error Handling
| Error | Cause | Solution |
|---|
| Cache stampede | TTL expires simultaneously for popular key; many requests hit database | Use lock-based revalidation (only one request refreshes); apply jittered TTLs |
| Stale data served | Cache invalidation missed a related resource after mutation | Implement tag-based invalidation covering all affected cache keys; add invalidation audit logging |
| Redis connection failure | Cache store unavailable due to network or server issue | Fall through to database with degraded performance; log cache bypass; alert on sustained failures |
| Cache key collision | Different requests generating identical cache keys | Include all varying parameters in key; hash the full normalized request for uniqueness |
| Memory pressure | Cache grows unbounded consuming all available Redis memory | Configure Redis maxmemory-policy to allkeys-lru; set per-key size limits; monitor memory usage |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
Product catalog caching: Cache GET /products list for 5 minutes and GET /products/:id for 1 hour, invalidating both when any product is created, updated, or deleted via tag products.
User-specific dashboard: Cache dashboard data per user using cache:dashboard:{userId} keys with 30-second TTL, serving stale data during revalidation to keep perceived response time under 50ms.
CDN edge caching: Set Cache-Control: public, max-age=300, stale-while-revalidate=60 on public endpoints, enabling CloudFront to serve cached responses at the edge while revalidating asynchronously.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
