Cache API: Manual Control Over Network Responses

Why it exists

The browser's standard HTTP cache is automatic and opaque. Developers needed a low-level, scriptable API to explicitly control caching logic, especially for building reliable offline experiences and performance-critical applications. The Cache API provides this direct control over request/response pairs.

The mental model

The Cache API provides a persistent storage mechanism for Request and Response pairs. Think of it as a set of named, versionable hash maps that you manage yourself. Unlike the browser's HTTP cache, nothing happens automatically; you decide what to store, when to retrieve it, and when to delete it. It's available in both the main window and web workers, but its most common use is within a service worker.

How it works

You first open a named cache using CacheStorage.open('my-cache-v1'). This returns a promise that resolves with a Cache object. You can then use methods like add() or addAll() to fetch URLs and store their responses, or put() to store a Request/Response pair you already have. To retrieve an item, you use match(request), which returns the corresponding Response. Deletion is done explicitly with delete(request). All these operations are asynchronous and return Promises.

When to use it

The primary use case is inside a service worker to make a Progressive Web App (PWA) work offline. By intercepting fetch events, the service worker can check the cache first with cache.match(event.request) and return a stored response if available, falling back to the network otherwise. It's also used to pre-cache an application's "shell"—the minimal HTML, CSS, and JS—during the service worker's install event for instant subsequent loads.

When not to use it

Do not use it if you want the browser's standard, header-based caching behavior. The Cache API ignores Cache-Control, Expires, and ETag headers. If you just want to cache user-specific data that isn't a network response, IndexedDB is a more appropriate choice. The Cache API is specifically for request/response pairs.

One canonical example

A service worker caching its app shell on install. During the install event, it calls caches.open('app-shell-v1') and then uses the addAll() method with an array of URLs like ['/', '/styles.css', '/app.js']. On subsequent visits, the service worker's fetch event handler can intercept requests for these assets and serve them directly from the cache, making the app load instantly. A common footgun is forgetting to manage old caches; when a new service worker activates, it should delete caches from previous versions.