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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| lru-cache with a TTL | Node, and an API that sends no cache headers | You pick the TTL and own every stale read, and its key decides who shares an entry | The API sends freshness and validators |
| NSwag fetch seam | An NSwag TypeScript client, where the constructor takes any fetch | No cache option of its own, so either kind of cache is code you add | You want a cache switched on by configuration |
| sandrolain/httpcache | A Go client that takes an *http.Client | Its release of 2026-11-13 asks for Go 1.26 and names 23 direct requirements | Your Go toolchain is pinned below 1.26 |
| sdkgen cache feature | An sdkgen SDK and an API with no cache headers | It reads no Cache-Control or ETag, and keys on method and URL alone | The API sends freshness and validators you want honored |
| Swagger Codegen fetch seam | A typescript-fetch client, whose BaseAPI takes a fetch as its third argument | No cache option among its ten settings, and it imports isomorphic-fetch at load | You want the client and its cache from one generator |
| undici cache interceptor | Node, and an API that sends max-age or s-maxage and an ETag | Stores nothing without cache headers unless cacheByDefault is set, and no authenticated response lacking public, s-maxage, or must-revalidate | The 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.
Related how-tos
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
-
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 neitherCache-ControlnorLast-Modifiedgives 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 -
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 -
That rule is section 3.5 of RFC 9111, which addresses it to a shared cache. undici 8.13.1 applies it in
canCacheResponse, inlib/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 runtype: 'private'therefore changed nothing for the per-user profile, andcacheByDefaultnothing for the bare one. ↩︎ Back to text