Skip to main content

​
Overview

Backend caching stores responses from your upstream services, reducing load on backends and improving response times. KrakenD respects standard HTTP cache headers and provides flexible caching strategies.

​
Example: Cached Market Data

The /market/cached endpoint demonstrates caching for cryptocurrency market data from the CoinGecko API.

​
Try It

# First request - hits the backend
curl -i http://localhost:8080/market/cached

# Subsequent requests - served from cache
curl -i http://localhost:8080/market/cached
Check the response headers to see cache status.

​
Configuration

From config/krakend/krakend.json: 
{
  "endpoint": "/market/cached",
  "backend": [
    {
      "host": ["https://api.coingecko.com"],
      "url_pattern": "/api/v3/coins/markets?vs_currency=eur&ids=bitcoin%2Cethereum&order=market_cap_desc&per_page=100&page=1&sparkline=false",
      "encoding": "safejson",
      "mapping": {
        "collection": "coins"
      },
      "extra_config": {
        "qos/http-cache": {
          "shared": true
        }
      }
    }
  ]
}

​
How It Works

​
HTTP Cache Component

"extra_config": {
  "qos/http-cache": {
    "shared": true
  }
}
The qos/http-cache component enables HTTP-based caching that respects standard cache control headers from the backend.

​
Shared Cache

"shared": true
When shared is true, the cache is shared across all clients. This is efficient for public data like market prices. Set to false for user-specific data where each user should have their own cache.

​
Cache Behavior

KrakenD’s HTTP cache respects these standard headers from the backend:
  • Cache-Control: max-age=3600 - Cache for 1 hour
  • Cache-Control: no-cache - Always revalidate
  • Cache-Control: no-store - Do not cache
  • Expires - Explicit expiration time
  • ETag - Conditional requests
  • Last-Modified - Conditional requests

​
Cache TTL Priority

KrakenD determines cache duration in this order:
  1. Backend Cache-Control headers (if HTTP cache is enabled)
  2. Endpoint-level cache_ttl (if set)
  3. Global cache_ttl (from main configuration)

​
Global Cache TTL

The playground sets a global default: 
{
  "version": 3,
  "cache_ttl": "300s",
  "endpoints": [...]
}
All endpoints inherit this 5-minute cache unless overridden.

​
Endpoint-Specific Cache

Override cache duration per endpoint: 
{
  "endpoint": "/public",
  "cache_ttl": "1s",
  "backend": [
    {
      "url_pattern": "/hotels/1.json"
    }
  ]
}
This endpoint caches for only 1 second, regardless of the global setting.

​
Cache Strategies

​
Shared Public Cache

Best for public data that’s the same for all users: 
"qos/http-cache": {
  "shared": true
}
Use Cases:
  • Public API data (weather, stocks, crypto prices)
  • Product catalogs
  • News feeds
  • Static reference data

​
Private Cache

Best for user-specific data: 
"qos/http-cache": {
  "shared": false
}
Use Cases:
  • User profiles
  • Personalized recommendations
  • Shopping carts
  • Private messages

​
Disable Caching

To disable caching for an endpoint: 
{
  "endpoint": "/real-time-data",
  "cache_ttl": "0s",
  "backend": [...]
}
Or explicitly skip HTTP cache: 
"extra_config": {
  "qos/http-cache": {
    "shared": false
  }
}

​
Cache Headers in Response

KrakenD adds headers to indicate cache status: 
HTTP/1.1 200 OK
X-Cache: HIT
X-Cache-Lookup: HIT
Age: 45
  • X-Cache: HIT - Response served from cache
  • X-Cache: MISS - Response fetched from backend
  • Age: 45 - Response has been cached for 45 seconds

​
Performance Benefits

​
Without Caching

Every request hits the backend: 
Client → KrakenD → CoinGecko API (200ms)
Client → KrakenD → CoinGecko API (200ms)
Client → KrakenD → CoinGecko API (200ms)
Total backend calls: 3
Total latency: 600ms

​
With Caching

Client → KrakenD → CoinGecko API (200ms) [MISS]
Client → KrakenD (from cache, 2ms)       [HIT]
Client → KrakenD (from cache, 2ms)       [HIT]
Total backend calls: 1
Total latency: 204ms
Performance improvement: 66% faster

​
Best Practices

​
1. Cache Stable Data

✅ Good candidates:
  • Product catalogs
  • Configuration data
  • Historical data
  • Aggregated statistics
❌ Bad candidates:
  • Real-time stock prices
  • Live sports scores
  • User authentication status
  • Shopping cart contents

​
2. Set Appropriate TTL

// Frequently changing data
"cache_ttl": "10s"

// Moderate change frequency
"cache_ttl": "5m"

// Rarely changing data
"cache_ttl": "1h"

// Static data
"cache_ttl": "24h"

​
3. Respect Backend Headers

Always enable HTTP cache for backends that provide proper cache headers: 
"qos/http-cache": {
  "shared": true
}

​
4. Monitor Cache Hit Rate

Use Grafana metrics to track:
  • Cache hit rate
  • Cache miss rate
  • Backend request reduction

​
Advanced Caching

​
Vary by Query Parameters

KrakenD automatically varies cache by endpoint path and query parameters: 
/market/cached?currency=usd  (separate cache entry)
/market/cached?currency=eur  (separate cache entry)

​
Vary by Headers

For user-specific caching: 
"qos/http-cache": {
  "shared": false
}
This creates separate cache entries per user (based on headers like Authorization).

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us