How-to › Make calls that survive failure

How to choose a TTL cache or an HTTP cache for a read-heavy API#

Read the API's cache headers, then run one workload through an HTTP-aware cache and a TTL cache to compare origin requests, stale reads, and leaks.

Audience
API consumer
Level
intermediate
Topic
Cache API responses
Languages
TypeScript, Python and Go
Verified

Your integration reads the same product price thousands of times an hour. You add an RFC 9111 cache under the client, and the origin’s request count does not move, because the API sends no Cache-Control at all. You swap in a plain TTL cache, and requests drop, but a customer logged in as Bob is shown Alice’s discounted price.

What you get

You will end up with a choice between an HTTP-aware cache and a TTL cache, measured on one API’s headers, origin request count, and stale seconds. This is for you if you consume an API and own the client that calls it.

Short answer

Dump the API’s response headers before choosing. If it sends max-age and an ETag, an HTTP-aware cache such as undici’s interceptor follows them unprompted, and stores an authenticated response only when it is public. If it sends no cache headers, that cache stores nothing by default. A TTL cache such as lru-cache or the sdkgen cache feature then cuts traffic, at a staleness window you choose. Per-caller responses need a cache per caller.

You will need

Node 22.19 or later and read access to the API. Verified 2026-11-21 against Node 22.23.5, undici 8.13.1, lru-cache 11.5.3, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, Swagger Codegen 3.0.85 and NSwag 14.8.0. The sample’s api.json describes one product read and one update, and a stand-in on 127.0.0.1 answers them with three header profiles. Every run here uses a clock the script controls, so 150 seconds of reads take under a second.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
lru-cache with a TTLNode, and an API that sends no cache headersYou pick the TTL and own every stale read, and its key decides who shares an entryThe API sends freshness and validators
NSwag fetch seamAn NSwag TypeScript client, where the constructor takes any fetchNo cache option of its own, so either kind of cache is code you addYou want a cache switched on by configuration
sandrolain/httpcacheA Go client that takes an *http.ClientIts release of 2026-11-13 asks for Go 1.26 and names 23 direct requirementsYour Go toolchain is pinned below 1.26
sdkgen cache featureAn sdkgen SDK and an API with no cache headersIt reads no Cache-Control or ETag, and keys on method and URL aloneThe API sends freshness and validators you want honored
Swagger Codegen fetch seamA typescript-fetch client, whose BaseAPI takes a fetch as its third argumentNo cache option among its ten settings, and it imports isomorphic-fetch at loadYou want the client and its cache from one generator
undici cache interceptorNode, and an API that sends max-age or s-maxage and an ETagStores nothing without cache headers unless cacheByDefault is set, and no authenticated response lacking public, s-maxage, or must-revalidateThe API sends no cache headers

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

The two generator rows are seams, not caches. Swagger Codegen and NSwag generate no cache, so a reader of either plugs undici or lru-cache under the client. The HTTP-aware rows are correct for free when the API sends the right headers and inert when it does not. The TTL rows work against any API, and every stale read and every cache-bust is then yours.

Read the API’s headers before choosing

The decision is made by headers you can see in one request. workload.mjs headers asks the stand-in once under each profile and prints five of the headers a cache reads:

node workload.mjs headers
public    cache-control: public, max-age=60  etag: "p1-v1"  vary: -  last-modified: -  expires: -
bare      cache-control: -  etag: -  vary: -  last-modified: -  expires: -
per-user  cache-control: private, max-age=60  etag: "p1-v1-bob"  vary: Authorization  last-modified: -  expires: -

Against a real API, curl -sI on the endpoint shows the same fields. bare leaves an HTTP cache nothing to work with. RFC 9111 lets a cache store a response with no explicit freshness only under a heuristic, which undici applies only to responses with Last-Modified.1 Its cacheByDefault option sets a freshness for the rest. per-user sends private, which tells a shared cache not to store it.

Run one workload through both kinds of cache

Each option reads product p1 once a second for 150 seconds, and the price changes upstream at 30 seconds. undici sits under the Swagger Codegen client, lru-cache under the NSwag client, and sdkgen uses its own cache feature with a 60 second ttl.

node workload.mjs
public: 150 reads, one a second; the price changes upstream at 30 s
cache                                                  200s   304s   stale reads
no cache (Swagger Codegen client)                      150    0      0
undici cache (Swagger Codegen client)                  3      1      31
undici, cacheByDefault 60000 (Swagger Codegen client)  3      1      31
lru-cache, ttl 60 s (NSwag client)                     3      0      31
sdkgen cache feature, ttl 60 s                         3      0      30
bare: 150 reads, one a second; the price changes upstream at 30 s
cache                                                  200s   304s   stale reads
no cache (Swagger Codegen client)                      150    0      0
undici cache (Swagger Codegen client)                  150    0      0
undici, cacheByDefault 60000 (Swagger Codegen client)  150    0      0
lru-cache, ttl 60 s (NSwag client)                     3      0      31
sdkgen cache feature, ttl 60 s                         3      0      30

Under public, the HTTP cache matched the TTL caches with no TTL of its own, and its revalidation came back as one 304. Under bare, undici sent all 150 reads to the origin, and the TTL caches cut them to three, serving the old price for about 30 seconds after the change. That window is the price of the TTL, and it is set by your number, not by the API.2 undici’s cacheByDefault option, a freshness for responses that state none, changed nothing in the bare rows: every request here carries Authorization, and the per-user run below shows what undici does with those. Its documentation gives the option no unit. The source adds it beside max-age * 1000, and a test shows 60000 keeping an entry for 59 seconds and not for 61.

After that 304, undici sent its next read without If-None-Match and fetched the whole body again. revalidation.mjs reproduces it on a bare node:http origin: a 304 that carries Cache-Control is followed by an unconditional request, and one without it is followed by a revalidation on every read.

Put the cache under a generated client

Swagger Codegen and NSwag generate no cache. The ten entries in the typescript-fetch option list include no cache setting, and NSwag’s TypeScript generator page documents none. Both clients take a fetch function, which is where either cache goes:

export const clients = {
  swagger: ({ base, fetch, token }) => {
    const api = new DefaultApi(undefined, base, withToken(fetch, token))
    return async (id) => (await api.getProduct(id)).price
  },
  nswag: ({ base, fetch, token }) => {
    const client = new Client(base, { fetch: withToken(fetch, token) })
    return async (id) => (await client.getProduct(id)).price
  },

withToken adds the caller’s Authorization on the way into the cache, so the cache sees the header. sdkgen needs no wrapper: feature: { cache: { active: true, ttl, now } } in the constructor turns on a TTL cache that, as its features reference puts it, does not read Cache-Control or revalidate with ETag. A Go reader wraps the http.Client instead: sandrolain/httpcache for the HTTP-aware kind, or a RoundTripper over golang-lru’s expirable package for a TTL. In Python, hishel and cachetools.TTLCache are the same pair.

Check it worked

Eleven tests hold every number on this page. They cover the profiles, the workloads, the callers, the 304, the unit of cacheByDefault, a write through each cache, and a stand-in that refuses what the API would.

node --test cache.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0

When it goes wrong

Bob sees Alice’s price. A TTL cache keyed on method and URL served one caller’s response to the other. Give each caller its own cache, or put the caller in the key:

node workload.mjs per-user
two callers, 60 reads each, one a second; alice pays 36 and bob 40
cache                                                  200s   304s   wrong-caller answers
undici cache, shared (Swagger Codegen client)          120    0      0
undici cache, private (Swagger Codegen client)         120    0      0
lru-cache, ttl 60 s, one for both (NSwag client)       1      0      60
sdkgen cache feature, a client per caller              2      0      0

The shared lru-cache answered all 60 of Bob’s reads with Alice’s price. sdkgen kept the two apart because each client holds its own store; one client shared across callers would have the same key. undici leaked nothing and also stored nothing, even with type: 'private', because it refuses a response to a request with Authorization unless the response is public, s-maxage or must-revalidate.3

A price you just changed comes back old. The sdkgen cache feature keeps its entry when the same client writes, so the read after an update returns the cached body until ttl runs out:

node workload.mjs own-write
one read, a write of 50 through the same client, then 70 reads one a second
cache                                                  reads of the old price
undici cache (Swagger Codegen client)                  0
lru-cache, ttl 60 s (NSwag client)                     0
sdkgen cache feature, ttl 60 s                         59

undici drops the entry on a write, as section 4.4 of RFC 9111 requires. ttlCacheFetch does the same, and it also declines to store a read that a write overtook. The feature’s options, ttl, max, methods and now, include no way to drop an entry, so keep its ttl as short as a stale price allows.

The cache stores nothing at all. The API sends no Cache-Control, and an HTTP-aware cache is doing its job. Read the headers again, and use a TTL cache or ask the API’s owner for max-age.

When not to do this

Do not put a TTL cache in front of an API that already sends max-age and an ETag. You replace the owner’s freshness with your guess, and you lose the cheap 304 revalidation.

Do not use the sdkgen cache feature against an API that sends no-store, or for per-caller data on one shared client. It reads no Cache-Control, as its reference says, so no-store does not stop it.

Do not switch generators for a cache. Swagger Codegen and NSwag clients take a fetch, which holds either kind. NSwag is the better fit when you want a client you can read in one sitting: its TypeScript here is one file of 189 lines, beside sdkgen’s 51 compiled files. Swagger Codegen suits a reader who wants an RFC 9111 cache under it, because nothing in its client competes with one.

Last verified

Verified 2026-11-21 against Node 22.23.5, undici 8.13.1, lru-cache 11.5.3, isomorphic-fetch 3.0.0, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, Swagger Codegen 3.0.85 and NSwag 14.8.0. Every output block is what the command preceding it printed. The three clients were generated once by generate.sh and their compiled JavaScript is committed. NSwag ran on the .NET 10.0.15 runtime for that one run. The Go and Python libraries named here were not run; what the page says of them comes from their own documentation and, for sandrolain/httpcache, its module file on the Go proxy.

Footnotes

  1. RFC 9111 allows heuristic freshness and suggests a fraction of the time since Last-Modified, offering 10% as a typical setting. An API that sends neither Cache-Control nor Last-Modified gives a heuristic nothing to take a tenth of. The same section notes that earlier specifications called heuristically cacheable status codes “cacheable by default”, which is close to the name undici gave its option. ↩︎ Back to text

  2. The 30 and the 31 are the same window counted two ways, and the RFC holds both. Section 4.2 calls a response fresh while its age “has not yet exceeded” its freshness lifetime, and gives the calculation further down the same section as freshness_lifetime > current_age. undici and lru-cache served the sixtieth second from the cache, in the spirit of the sentence, and sdkgen expired it, in the spirit of the formula. ↩︎ Back to text

  3. That rule is section 3.5 of RFC 9111, which addresses it to a shared cache. undici 8.13.1 applies it in canCacheResponse, in lib/handler/cache-handler.js, with no test of the cache type it was given, and its documentation states it only under the SQLite store. In this run type: 'private' therefore changed nothing for the per-user profile, and cacheByDefault nothing for the bare one. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.