HTTP Caching Headers: Complete Developer Guide

from flask import Flask, make_response
import datetime

app = Flask(__name__)

@app.route('/api/public-data')
def public_data():
    response = make_response({"data": "This is publicly cached"})
    response.headers['Cache-Control'] = 'public, max-age=3600, must-revalidate'
    return response

@app.route('/api/user-profile')
def user_profile():
    response = make_response({"user": "private data"})
    response.headers['Cache-Control'] = 'private, max-age=300'
    return response

@app.route('/api/sensitive')
def sensitive():
    response = make_response({"secret": "do not cache"})
    response.headers['Cache-Control'] = 'no-store'
    return response

print("Caching endpoints configured")

# Testing Cache-Control behavior
import requests

cache_configs = [
    "public, max-age=3600",
    "private, max-age=300",
    "no-cache",
    "no-store",
    "public, max-age=86400, immutable",
]

for config in cache_configs:
    if "max-age" in config:
        seconds = config.split("max-age=")[1].split(",")[0]
        print(f"{config:45} → cacheable for {seconds}s")
    elif config == "no-cache":
        print(f"{config:45} → must revalidate with server")
    elif config == "no-store":
        print(f"{config:45} → DO NOT CACHE")

import hashlib
import json

class ETagCache:
    def __init__(self):
        self.resources = {}

    def get_or_update(self, resource_id, data):
        content = json.dumps(data, sort_keys=True).encode()
        new_etag = hashlib.md5(content).hexdigest()

        if resource_id in self.resources:
            old_etag = self.resources[resource_id]
            if old_etag == new_etag:
                return None, new_etag  # 304 Not Modified

        self.resources[resource_id] = new_etag
        return data, new_etag  # 200 OK

cache = ETagCache()

# First request
data = {"version": 1, "items": [1, 2, 3]}
result, etag = cache.get_or_update("list", data)
print(f"First request:  {'200 (new)' if result else '304 (cached)'}, ETag: {etag[:12]}...")

# Same data — no change
result, etag = cache.get_or_update("list", data)
print(f"Second request: {'200 (new)' if result else '304 (cached)'}, ETag: {etag[:12]}...")

from datetime import datetime, timedelta
import time

def generate_last_modified():
    # Generate a timestamp for the resource
    last_mod = datetime.utcnow()
    return last_mod.strftime('%a, %d %b %Y %H:%M:%S GMT')

def check_if_modified_since(header_value):
    if not header_value:
        return True  # No header, send full response

    # Parse the If-Modified-Since header
    client_time = datetime.strptime(
        header_value.replace(' GMT', ''),
        '%a, %d %b %Y %H:%M:%S'
    )
    server_time = datetime.utcnow()

    return server_time > client_time  # True if modified

# Simulate two requests, 2 seconds apart
last_mod = generate_last_modified()
print(f"Response header: Last-Modified: {last_mod}")

time.sleep(0.1)  # Simulate short delay

# Client sends If-Modified-Since
needs_update = check_if_modified_since(last_mod)
print(f"Client said: If-Modified-Since: {last_mod}")
print(f"Resource modified? {'Yes' if needs_update else 'No — send 304'}")

@app.route('/api/content')
def content():
    # Content varies based on Accept-Language
    lang = request.headers.get('Accept-Language', 'en')

    response = make_response({
        "content": f"Content in {lang}",
        "requested_lang": lang
    })
    response.headers['Cache-Control'] = 'public, max-age=3600'
    response.headers['Vary'] = 'Accept-Language, Accept-Encoding'
    return response

# Configuring CDN caching headers (pseudo-configuration)
cdn_config = {
    "static_assets": {
        "path": "/static/*",
        "headers": {
            "Cache-Control": "public, max-age=31536000, immutable",
        },
        "cdn_ttl": 86400,  # CDN caches for 1 day
        "origin_ttl": 31536000,  # Browser caches for 1 year
    },
    "api_responses": {
        "path": "/api/*",
        "headers": {
            "Cache-Control": "no-cache",
            "Surrogate-Control": "max-age=60",  # CDN-specific
        },
        "cdn_ttl": 60,  # CDN caches for 1 minute
    },
}

for name, config in cdn_config.items():
    print(f"{name}:")
    print(f"  Path: {config['path']}")
    print(f"  Browser cache: {config['headers']['Cache-Control']}")
    print(f"  CDN TTL: {config['cdn_ttl']}s")

// service-worker.js (conceptual)
self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request)
      .then(cached => {
        // Cache-first strategy
        if (cached) return cached;

        return fetch(event.request).then(response => {
          return caches.open('v1').then(cache => {
            cache.put(event.request, response.clone());
            return response;
          });
        });
      })
  );
});

# Cache invalidation patterns
strategies = {
    "Time-based (TTL)": "Set max-age and let cache expire naturally",
    "Versioned URLs": "Add version hash to filename: app.v2.js",
    "Cache purge": "CDN API call to invalidate specific URLs",
    "Key-based": "Include version in cache key: cache:users:v2:42",
    "Stale-while-revalidate": "Serve stale cache, refresh in background",
}

for strategy, description in strategies.items():
    print(f"{strategy:30} → {description}")