Caching & ETags

Every cacheable response carries a strong ETag and a Cache-Control. Sending the ETag back on your next request turns a full response into a 304 Not Modified, which touches no database row and costs no credits.

That is a deliberate incentive, not an oversight. A client that resynchronises often is the client we want, and charging for the privilege would push you towards polling less and being more stale.

The round trip

# First call — full body, note the ETag
curl -si "https://api.pokemontcgapi.com/v1/sets/sv3" -H "X-Api-Key: $PTCG_API_KEY" | grep -i etag
# etag: "o6DkBk61AqCBy1I5NtiqFLhjA8a"

# Second call — unchanged, so 304 and no body
curl -si "https://api.pokemontcgapi.com/v1/sets/sv3" \
  -H "X-Api-Key: $PTCG_API_KEY" \
  -H 'If-None-Match: "o6DkBk61AqCBy1I5NtiqFLhjA8a"'
# HTTP/2 304

The 304 still carries ETag and Cache-Control, so the next validation starts from a fresh baseline rather than from nothing.

A caching client

const store = new Map<string, { etag: string; body: unknown }>();

export async function cachedGet(url: string, key: string): Promise<unknown> {
  const hit = store.get(url);

  const res = await fetch(url, {
    headers: {
      "X-Api-Key": key,
      ...(hit ? { "If-None-Match": hit.etag } : {}),
    },
  });

  // 304 means what we already hold is still current. No body is sent,
  // so reading one here would hang.
  if (res.status === 304 && hit) return hit.body;
  if (!res.ok) throw new Error((await res.json()).error.code);

  const body = await res.json();
  const etag = res.headers.get("ETag");
  if (etag) store.set(url, { etag, body });

  return body;
}

Cache policy by family

Read from the live API on 2026-08-27.

What the ETag is computed from

A SHA-256 over the canonical serialised body, truncated to 27 base64url characters. It is a strong validator: identical ETag means byte-identical body.

• The ETag changes when the response changes, which includes changes caused by your own parameters — select, include, lang and limit all produce different bodies and therefore different ETags.
• Key by full URL, not by resource id. Two select lists on the same card are two cache entries.
• Weak comparison (W/"…") is accepted on the way in, so an intermediary that weakened your validator does not break revalidation.
• If-None-Match: * always matches, which is occasionally handy in tests.

Where to put a cache

In your process

An LRU keyed by URL is enough for read-heavy apps and takes ten lines, as above. Bound it — the catalogue is bigger than your heap.

At the edge

Catalogue responses are public, so a CDN or shared cache in front of your service works without configuration. stale-while-revalidate=600 means users get an instant answer while the refresh happens behind them.

In your database

If you mirror the catalogue, do not revalidate row by row. Every card carries updated_at and a monotonic row_version; store the highest updated_at you have imported and re-read only the sets whose cards moved past it. Sets change on a release schedule, so most nights that is a handful of requests rather than a full walk.

Compression

Responses are compressed with Brotli or gzip according to your Accept-Encoding. On 2026-08-27, GET /v1/cards?limit=50 was 40,568 bytes uncompressed, 2,133 with Accept-Encoding: br and 2,300 with gzip — a 95% reduction either way, because JSON with repeating keys is close to the best case for a dictionary coder.

Most HTTP clients negotiate this already. If yours does not, sending the header is a one-line change with a twenty-fold payoff on bandwidth.