# 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.

Source: https://voxgig.com/howto/choose-ttl-cache-over-http-cache

- Audience: api-consumer
- Level: intermediate
- Languages: typescript, python, go
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](https://isaacs.github.io/node-lru-cache/) | 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](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator) | 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](https://github.com/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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | 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](https://generator3.swagger.io/api/options?language=typescript-fetch&version=V3) | 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](https://github.com/nodejs/undici/blob/v8.13.1/docs/docs/api/Interceptors.md) | 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:

```bash
node workload.mjs headers
```

```text output
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`.

```bash
node workload.mjs
```

```text output
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](https://generator3.swagger.io/api/options?language=typescript-fetch&version=V3)
include no cache setting, and NSwag's
[TypeScript generator page](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator)
documents none. Both clients take a fetch function, which is where either cache goes:

```js title="caches.mjs"
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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md)
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`](https://pkg.go.dev/github.com/hashicorp/golang-lru/v2/expirable) package
for a TTL. In Python, [`hishel`](https://hishel.com/) and
[`cachetools.TTLCache`](https://cachetools.readthedocs.io/en/stable/) 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.

```bash
node --test cache.test.mjs
```

```text output
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:

```bash
node workload.mjs per-user
```

```text output
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:

```bash
node workload.mjs own-write
```

```text output
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](https://www.rfc-editor.org/rfc/rfc9111.html#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

- [Add a response cache to a third-party SDK](/howto/cache-responses-in-a-third-party-sdk)

- [Choose Cache-Control values for private and shared caches](/howto/choose-cache-control-directives-for-api-responses)

- [Build cache keys that include the caller and Vary headers](/howto/cache-keys-that-include-the-caller)

- [Invalidate a cached list after a create call](/howto/invalidate-cached-list-after-create)

## 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.

[^1]: [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html#section-4.2.2) 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.

[^2]: The 30 and the 31 are the same window counted two ways, and the RFC holds both.
[Section 4.2](https://www.rfc-editor.org/rfc/rfc9111.html#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.

[^3]: That rule is [section 3.5](https://www.rfc-editor.org/rfc/rfc9111.html#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`](https://github.com/nodejs/undici/blob/v8.13.1/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.