Cache a function's response with the Cache API

Store a response a function builds with the runtime Cache API, return it on later requests, and delete it when the data behind it changes.

Last updated

View as Markdown Agent setup

You store a response that a function builds with the runtime Cache API, return the stored copy on later requests, and delete it when the data behind it changes. To cache responses without a function, with a rule on an application, refer to Cache settings.

A function that builds the same response for the same input, such as a list read from a database or the output of a model call, can keep that response and skip the work on the next request. The key decides which requests share one stored copy, and a write that changes the data deletes the copy, so the next request builds it again.

  1. The function builds a key for the request: the request URL, or a URL string that carries a hash of the input.
  2. When the cache holds an entry under the key, the function returns it and does no other work.
  3. Otherwise the function builds the response with a cache-control: max-age header, stores a copy, and returns the response.
  4. When a write changes the data a stored response was built from, the function deletes the entry under that key.

Prerequisites

  • A function to add the code to, deployed and instantiated on an application. To create one, refer to Functions quickstart.

The Cache API runs only on a deployed function. Under azion dev, caches is not defined, and any call throws ReferenceError: caches is not defined. Test the code once the function runs on the application.

The examples open a cache named my-cache, store responses for 3600 seconds, and answer on www.example.com. Replace them with your own values.

Build the key for the request

A Cache stores each response under a key, which is a Request object or a URL string, and put accepts only a GET request. A GET request can be its own key. A request whose input travels in the body, such as a POST, needs a URL string instead, or put throws TypeError: Request method must be GET. Build that string from a SHA-256 hash of the input, so the same input always yields the same key and a different input yields a different one.

To build the key, add these two helpers to the function:

JavaScript
01// SHA-256 of a string, as 64 hexadecimal characters.
02async function sha256(text) {
03 const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
04 return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
05}
06
07// A GET request keys on its own URL. Any other request keys on a hash of its input.
08async function cacheKey(request, input) {
09 const url = new URL(request.url);
10 if (request.method === 'GET') {
11 return `${url.origin}${url.pathname}${url.search}`;
12 }
13 return `${url.origin}/cache/${await sha256(input)}`;
14}

crypto.subtle.digest with SHA-256 returns 32 bytes, which the helper writes as 64 hexadecimal characters. Two POST requests carrying the same input get the same key.

Store the response and return it on a match

match returns the response stored under the key, or no response when the key has no entry. A stored response is matched by later requests only when it carries cache-control: max-age. A response stored without that header is not matched by a later request, so every request rebuilds it. Store a clone of the response with put, and return the original.

To cache the response of a POST request keyed by its body, use this handler with the two helpers:

JavaScript
01const CACHE_NAME = 'my-cache';
02const MAX_AGE = 3600;
03
04// Replace with the work whose result the function caches.
05async function buildBody(input) {
06 return { input, length: input.length };
07}
08
09export default {
10 async fetch(request, env, ctx) {
11 if (request.method !== 'POST') {
12 return new Response('Method not allowed', { status: 405 });
13 }
14 const input = await request.text();
15 const cache = await caches.open(CACHE_NAME);
16 const key = await cacheKey(request, input);
17
18 const cached = await cache.match(key);
19 if (cached) {
20 return cached;
21 }
22
23 const response = new Response(JSON.stringify(await buildBody(input)), {
24 headers: {
25 'content-type': 'application/json',
26 'cache-control': `max-age=${MAX_AGE}`,
27 'x-stored-at': new Date().toISOString(),
28 },
29 });
30 await cache.put(key, response.clone());
31 return response;
32 },
33};

The x-stored-at header is set once, when the function stores the response, so two responses that carry the same value came from the same stored copy.

Deploy the function, then send the same body twice:

curl -i -X POST https://www.example.com/ -d 'the same input'

The second response carries the same x-stored-at value as the first, and buildBody does not run for it. A different body gets a new key and a new value. Every client that sends the same input receives the stored copy, so cache only responses that are the same for every client, and never one built from a client’s credentials.

Delete the entry after a write

A stored response does not follow the data it was built from. When a write changes that data, delete the entry in the same code path, with the key the read builds. delete removes the entry and returns true, and a later match for that key returns no response.

In a function that also serves a list on GET /api/items, call delete once a write to the list succeeds:

JavaScript
01const cache = await caches.open(CACHE_NAME);
02await cache.delete(`${new URL(request.url).origin}/api/items`);

The key must match the one the read stores, character for character: here, the list that GET /api/items stores under its own URL. The next request for the list finds no entry, builds the response from the changed data, and stores it again. Delete the entry only after the write succeeds, so a failed write leaves the stored copy in place.

Next steps

Cache APIEvery method of CacheStorage and Cache, how stored responses are matched, and the errors to expect.SubtleCryptoThe digest algorithms crypto.subtle supports, and the size of each hash.Build REST and GraphQL APIsAn API function that caches its list response and deletes it after every write.Add AI features to existing applicationsA summarization route that caches each summary under a hash of the text.Govern access to multiple AI modelsAn AI gateway that caches a model response when the caller allows it.