What is nginx proxy_cache and why use it for API responses?

proxy_cache is nginx's built-in response cache for proxied traffic. When a request passes through proxy_pass, nginx can write the upstream's response to disk and serve later matching requests from that file without contacting the backend. A shared memory zone holds the cache keys and metadata, so nginx can check whether a response is cached without reading the disk. The response bodies stay on disk, which lets the cache grow far beyond available RAM.

For APIs, this gives you three things:

  • Lower origin load. If a product catalog or configuration endpoint receives thousands of identical requests per minute, the backend generates the response once per TTL window instead of once per request. Database queries, serialization, and connection pool usage drop by the same ratio.
  • Lower latency on read-heavy paths. A cache hit costs a file read on the nginx host. The client skips the network hop to the upstream and the application's processing time.
  • Resilience during backend failures. nginx can be configured to return a previously cached response when the upstream times out or returns errors. Clients get slightly old data instead of a 502.

This approach fits platform and backend engineers who already own the nginx layer and run endpoints that are read-mostly and identical across callers.

This tutorial treats caching as explicit and opt-in. You enable it in specific location blocks that you have checked are safe to share. You do not turn it on for a whole server and hope nothing private gets cached. For simple read paths, this also moves caching logic out of application code. You avoid writing and maintaining an in-process cache or a separate cache client for each service.

Who should use nginx proxy_cache for APIs?

proxy_cache is a good fit for the following teams and workloads:

  • Platform, SRE, and infrastructure engineers who already run nginx as a reverse proxy or API gateway. The cache lives in the same config they already deploy and review. They don't need to add a new service.
  • Backend teams with read-heavy endpoints whose responses are identical across callers. Typical examples are product catalogs, public reference data, feature or configuration documents, search suggestions, and documentation or metadata APIs. If many clients ask for the same URL and get the same bytes, caching pays off.
  • Multi-tenant APIs where responses vary by a small, known set of inputs. Examples are a tenant ID, an API version header, or a response format. These values can go into the cache key without exploding the number of entries.
  • Organizations with several services behind one nginx tier. They can apply one consistent caching policy without changing each service's code.
  • Teams that need a stopgap during backend incidents. Serving stale responses keeps read endpoints answering while the upstream recovers.

It is a poor fit for engineers whose endpoints are mostly per-user, write-heavy, or strictly consistent. It also falls short when they need one cache shared across a large fleet. The section on when to avoid proxy_cache covers these cases and the alternatives.

How does nginx proxy_cache work from request to cache file?

How does it work, in short? nginx turns each request into a cache key and looks the key up in shared memory. On a hit it serves the stored response from disk. On a miss it proxies to the upstream, returns the response to the client, and saves a copy if the response is cacheable. Freshness rules decide how long a copy can be served, and eviction rules decide how long it is kept. The details follow.

When a request reaches a location with proxy_cache enabled, nginx builds the cache key from proxy_cache_key. The default is $scheme$proxy_host$request_uri. It hashes the key with MD5 and looks up the hash in the shared-memory zone defined by keys_zone. That zone holds only metadata (keys, expiry, usage), so the lookup never touches disk. On a HIT, nginx reads the response from the file named by the hash. On a MISS, or when an entry has expired, it proxies to the upstream. If the response is cacheable, nginx streams it to the client and writes it to disk.

Freshness comes from proxy_cache_valid or from upstream headers such as Cache-Control and Expires. proxy_cache_path controls storage. levels=1:2 spreads files across subdirectories so no single directory grows huge. keys_zone=api:10m names the zone and sizes it. The nginx docs estimate about 8,000 keys per megabyte. max_size caps disk usage. inactive removes entries that nobody has requested within that period, whether they are fresh or not. These are two separate controls: freshness decides whether nginx can serve an entry, and inactive decides whether the entry is worth keeping at all.

Each nginx instance keeps its own cache. Behind a load balancer with N instances, every instance has to miss once per key, so hit ratios fall as the fleet grows. During a TTL window, two instances can also return different versions of the same resource.

Sizing errors fail quietly. If keys_zone or max_size is too small, entries get evicted before they expire. If the cache sits on slow or shared disk, a HIT can be slower than a fast upstream.

http {
    # Cache storage: two-level directory hashing, 10 MB of shared memory
    # for keys/metadata (~80k keys), 5 GB disk cap, and eviction of
    # entries not requested for 60m regardless of freshness.
    proxy_cache_path /var/cache/nginx/api
                     levels=1:2
                     keys_zone=api:10m
                     max_size=5g
                     inactive=60m
                     use_temp_path=off;

    upstream api_backend {
        server 10.0.0.10:8080;
    }

    server {
        listen 80;

        location /api/ {
            proxy_pass
            proxy_cache api;

            # Explicit key (same as the default). Hashed with MD5 to
            # produce the on-disk file name.
            proxy_cache_key $scheme$proxy_host$request_uri;

            # Freshness: used only when upstream sends no Cache-Control
            # or Expires. Separate from 'inactive' above.
            proxy_cache_valid 200 5m;
            proxy_cache_valid 404 30s;

            # Expose HIT/MISS/EXPIRED per instance; each node has its own cache.
            add_header X-Cache-Status $upstream_cache_status always;
        }
    }
}

A minimal API cache configuration showing the proxy_cache_path storage parameters, an explicit cache key, freshness rules that are separate from inactive eviction, and a header that reports each instance's cache status.

How do you enable proxy_cache for specific API endpoints?

Turn caching on per location, not per server. A server-level proxy_cache applies to every route, including endpoints like /me, /cart, or admin APIs that nobody reviewed for caching. One upstream response without Cache-Control: private is then enough to serve one user's data to another. Opting in per location makes each cached endpoint a deliberate choice.

Designing the key

The default proxy_cache_key is $scheme$proxy_host$request_uri. It ignores headers entirely. If the response varies by something outside the URI, that thing must go into the key:

Response varies by Add to key Fragmentation risk
Tenant (X-Tenant-ID) $http_x_tenant_id Moderate: one copy per tenant
API version header $http_api_version Low: a few values
Content negotiation $http_accept High: raw Accept strings vary widely
Auth token Don't. Bypass instead Extreme: one entry per user

High-cardinality variables split one resource into many entries. Each entry needs its own upstream fetch, so the hit ratio falls, and the entries compete for keys_zone slots. Normalize values with map before they go into the key, for example by collapsing Accept to json or xml.

TTLs and precedence

Set proxy_cache_valid 200 5m; and proxy_cache_valid 404 30s;. Short 404 TTLs absorb scans for missing IDs without hiding newly created resources for long. If you give a time with no status codes, it applies only to 200, 301, and 302.

Upstream headers take precedence over these values. X-Accel-Expires wins first, followed by Expires and Cache-Control. Use proxy_ignore_headers only when nginx should own the TTL.

Defaults that surprise people

  • proxy_cache_methods covers only GET and HEAD.
  • Responses that carry Set-Cookie are not cached.
  • Responses marked Cache-Control: private, no-cache, or no-store are not cached.
proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:10m
                 max_size=1g inactive=10m use_temp_path=off;

map $http_accept $accept_variant {
    default             json;
    "~*application/xml" xml;
}

upstream api_backend { server 10.0.0.12:8080; }

server {
    listen 80;
    server_name api.example.com;
    # No proxy_cache here: caching is opt-in per location

    location /api/v1/products/ {
        proxy_pass
        proxy_cache api_cache;

        # Default key plus tenant and normalized format; never the auth token
        proxy_cache_key "$scheme$proxy_host$request_uri|$http_x_tenant_id|$accept_variant";

        # Fallback TTLs; upstream X-Accel-Expires, Expires, Cache-Control win
        proxy_cache_valid 200 5m;
        proxy_cache_valid 404 30s;

        # Authenticated requests skip the cache and are not stored
        proxy_cache_bypass $http_authorization;
        proxy_no_cache     $http_authorization;

        # proxy_cache_methods defaults to GET HEAD; POST/PUT pass through
        add_header X-Cache-Status $upstream_cache_status;
    }

    location /api/v1/me {
        # Per-user data: proxied but never cached
        proxy_pass
    }
}

Per-location proxy_cache with a tenant- and format-aware key, a map that normalizes Accept to limit fragmentation, per-status TTLs, and a bypass for authenticated requests.

How do cache bypass and proxy_no_cache keep per-user data from leaking?

The default proxy_cache_key is $scheme$proxy_host$request_uri, which contains no identity. If /api/me gets cached for Alice, Bob's request for /api/me produces the same key and receives Alice's response. Many backends set Cache-Control: private on authenticated responses, and that prevents this. But you cannot assume every endpoint does, so authenticated traffic needs its own guard in the Nginx config.

Two directives handle this, and they act at different points in the request:

Directive When it acts Effect if any value is non-empty and not "0"
proxy_cache_bypass Before lookup Skips the cache and fetches from the backend
proxy_no_cache After the backend responds Does not store the response

You usually need both. Bypass alone sends Bob's request to the backend, but his response can still be written to the cache under the shared key, and the next anonymous client may receive it. proxy_no_cache alone stops new entries from being stored, but a matching request can still be answered from an entry that already exists.

Build the condition once with map and pass the resulting variable to both directives. For example, map $http_authorization, $cookie_session, and a debug header such as $http_x_cache_skip so that each yields 1 when present and an empty string when absent. Because both directives accept several values and trigger on any non-empty one, you can list the variables without combining them yourself. To cache authenticated responses on purpose, put the user identity in the key instead.

Be careful with proxy_ignore_headers Set-Cookie Cache-Control. It forces Nginx to cache responses that the backend marked as per-user or uncacheable. That overrides the backend's explicit intent, and it is a common way to leak session cookies to other clients.

proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:10m
                 max_size=1g inactive=10m use_temp_path=off;

map $http_authorization $skip_auth    { default 1; "" 0; }
map $cookie_session     $skip_session { default 1; "" 0; }
map $http_x_cache_skip  $skip_debug   { default 1; "" 0; }

upstream api_backend {
    server 10.0.0.12:8080;
}

server {
    listen 80;
    server_name api.example.com;

    location /api/ {
        proxy_pass
        proxy_cache api_cache;
        proxy_cache_valid 200 1m;
        # Default key has no identity: $scheme$proxy_host$request_uri

        # Before lookup: never answer identified requests from cache.
        proxy_cache_bypass $skip_auth $skip_session $skip_debug;
        # After the response: never store what those requests return.
        proxy_no_cache     $skip_auth $skip_session $skip_debug;

        # Deliberately NOT set: proxy_ignore_headers Set-Cookie Cache-Control;
        # it would cache responses the backend marked private or uncacheable.

        add_header X-Cache-Status $upstream_cache_status always;
    }
}

One set of map variables built from the Authorization header, a session cookie, and a debug header is passed to both proxy_cache_bypass and proxy_no_cache, so requests that carry identity are neither answered from the shared cache nor written into it.

How do you serve stale content and prevent thundering herds?

Serving stale responses during failures and refreshes

proxy_cache_use_stale tells Nginx to return an expired entry instead of failing. A typical API setting is error timeout http_500 http_502 http_503 http_504 updating. Nginx has no http_5xx shorthand, so list each status code. The first parameters cover a backend that is down or slow. updating covers the normal refresh path: while one request fetches a fresh copy, other requests get the old one. Add proxy_cache_background_update on so that even the request that triggers the refresh gets the stale copy immediately, while a subrequest updates the cache. Background update only works when updating is in the stale list.

Nginx also honors the stale-while-revalidate and stale-if-error extensions in an upstream Cache-Control header. This lets the backend set stale windows per response instead of using one global policy. If you ignore Cache-Control with proxy_ignore_headers, Nginx drops these extensions too.

The trade-off: availability goes up, but clients can get outdated data for the entire stale window. For catalog data that is fine. For balances, inventory counts, or permission checks it is not, so turn stale serving off on those locations.

Collapsing concurrent misses

proxy_cache_lock on lets only one request per cache key go to the backend on a miss, and the rest wait for it. proxy_cache_lock_timeout limits how long they wait. After the timeout, a waiting request goes to the backend, but its response is not cached. proxy_cache_lock_age sets how long a populating request can run before Nginx lets another request through. Waiting requests add latency on every cold miss, so set these timeouts close to your backend's normal response time.

proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:10m
                 max_size=1g inactive=10m use_temp_path=off;

upstream api_backend {
    server 10.0.0.10:8080;
}

server {
    listen 80;
    server_name api.example.internal;

    location /v1/catalog/ {
        proxy_pass
        proxy_cache api_cache;
        proxy_cache_valid 200 60s;

        # Serve the expired entry if the backend is down or slow, or while a refresh runs.
        # There is no http_5xx shorthand, so list each status code.
        proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504 updating;
        # The request that triggers the refresh also gets the stale copy; a subrequest updates the cache.
        # Requires 'updating' in proxy_cache_use_stale.
        proxy_cache_background_update on;

        # On a cold miss, only one request per key goes to the backend.
        proxy_cache_lock on;
        # Waiters give up after 2s and go to the backend; that response is not cached.
        proxy_cache_lock_timeout 2s;
        # If the populating request runs longer than 3s, let one more request through.
        proxy_cache_lock_age 3s;
    }

    location /v1/balances/ {
        # Outdated balances are wrong answers: never cache or serve stale here.
        proxy_pass
        proxy_cache off;
    }
}

Stale serving with background refresh and cache locking for catalog data, while balance lookups bypass the cache entirely.

How do you verify cache behavior and invalidate entries?

Add $upstream_cache_status to a debug header with add_header X-Cache-Status $upstream_cache_status always; and to a custom log_format. The header lets you check a single request. The log field shows hit ratios per endpoint across real traffic. Run curl -sI against the same URL twice. The first response should report MISS and the second HIT. If both report MISS, the response is not being stored. Common causes are an upstream Set-Cookie header, Cache-Control: private, or a proxy_no_cache condition that matches.

Value Meaning
MISS Not in cache. Fetched from upstream and possibly stored.
HIT Served from a fresh cache entry.
EXPIRED The entry was stale, so Nginx fetched a fresh copy from upstream.
STALE A stale entry was served under proxy_cache_use_stale.
UPDATING A stale entry was served while another request refreshes it.
BYPASS proxy_cache_bypass matched, so the request went to upstream.
REVALIDATED proxy_cache_revalidate confirmed the entry with a conditional request.

Open-source Nginx has no built-in directive for targeted purge. After a write, clients receive the old response until the entry expires, unless the application coordinates invalidation. You have four options:

  • Short TTLs limit how long stale data can be served, at the cost of lower hit rates.
  • Versioned URLs or keys change the key when data changes, for example by adding a version segment to proxy_cache_key. Old entries are no longer requested and age out on their own.
  • Bypass headers let the backend refresh a hot entry right after a write. A request that matches proxy_cache_bypass but not proxy_no_cache fetches fresh content and overwrites the stored copy. Restrict that header to internal callers.
  • Deleting files under the cache path clears entries. Nginx treats a missing file as a miss. This method is blunt and hard to target per URL, so keep it for emergencies.

When should you avoid nginx proxy_cache, and what are the alternatives?

Some workloads are a poor fit for proxy_cache, and caching them adds risk without much benefit:

  • Highly personalized responses. If almost every response depends on the caller, the key has to include user identity. Hit rates collapse, and one mistake in the key can leak data between users.
  • Strong consistency requirements. Balances, inventory, and permissions cannot tolerate even a few seconds of staleness. Nginx has no awareness of writes happening in the backend.
  • Write-heavy endpoints. If data changes faster than the TTL, most entries are evicted or stale before anyone reads them.
  • Fleets that need a shared cache. Each nginx instance keeps its own cache on local disk. Ten nodes means ten cold caches, and purging has to reach every one of them.
Approach Where it lives Best for Main cost
HTTP caching (Cache-Control to clients and CDNs) Browser, CDN edge Public, cacheable resources Little control after a response is sent
Application-level cache (in-process or shared key-value store) Inside the service Per-user or computed data, write-aware invalidation Code in every service
Dedicated reverse-proxy cache layer Separate tier Shared cache across many nodes Another system to run

proxy_cache needs very little code. The ongoing cost is operational: someone has to design keys, size zones and disk, and debug stale or missing hits. The time savings come from centralizing caching. One nginx config can cache read-heavy endpoints across many services, so each team does not have to build, test, and maintain its own caching logic.

How can proxy_cache save engineering time?

The savings come from moving work out of application code and into configuration that one team owns:

  • No per-service cache code. Without a proxy cache, every service that wants caching needs its own implementation. That means a cache client or in-process store, key construction, TTL handling, serialization, and tests. With proxy_cache, enabling caching for a read endpoint means adding a location block. The service keeps working the same way.
  • One place to review and change policy. Keys, TTLs, bypass rules, and stale behavior sit in one nginx config that goes through normal review. Changing a TTL means editing and reloading the config, with no application redeploy. Applying the same bypass rule to authenticated traffic across many services is a single pattern, not a change in each codebase.
  • Backends control freshness through standard headers. Because nginx honors Cache-Control, Expires, and X-Accel-Expires, service teams can tune caching per response with headers they may already send. They don't have to learn a separate caching API.
  • Less urgent scaling work. When a read-heavy endpoint is served mostly from cache, the backend and database handle far fewer requests for it. That can postpone work such as adding read replicas or rewriting a slow query under deadline pressure.
  • Fewer incident escalations for read paths. With proxy_cache_use_stale and proxy_cache_background_update, read endpoints keep answering during short upstream failures. On-call engineers get time to fix the backend while clients keep receiving data.
  • Faster debugging. The X-Cache-Status header and the $upstream_cache_status log field show exactly how each request was handled. Engineers don't need to add instrumentation to every service to find out whether caching is working.

Illustrative estimate of origin load reduction (assumed inputs, not a measurement). Assume a catalog endpoint receives 2,000 identical requests per minute for one key, proxy_cache_valid 200 5m, four nginx instances, and proxy_cache_lock on. Over a 5-minute window that is 10,000 requests. Each instance fetches the key from the backend about once per TTL window, so the backend handles roughly 4 requests for that key instead of 10,000. Real numbers depend on how many distinct keys you have, how traffic spreads across instances, eviction from inactive or max_size, and how many requests bypass the cache.

These savings have limits. Someone still has to design keys carefully, size keys_zone and disk, decide which endpoints are safe to share, and plan invalidation. A mistake in any of these can cost more time than the cache saves, especially a key that leaks per-user data. The time savings are largest when many services share one nginx tier and their read endpoints are identical across callers.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nginx proxy_cache api, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.