Caching & conditional requests
Every response carries ETag: "<dataset_version>" and
Cache-Control: public, max-age=300 (/v1/dump and /v1/index:
max-age=3600). Once your cached copy expires, send If-None-Match with
the last ETag. If nothing changed, the API answers 304 Not Modified with
no body.
Send the ETag back exactly as received, quotes included. A proxy may hand
it to you weak (W/"e9c25a6"); that form matches too. Don’t compare it to
dataset_version yourself.
curl -D - -o /dev/null \ -H 'If-None-Match: "e9c25a6"' \ https://truefloat.app/api/v1/items/7/44/patternsHTTP/2 304etag: "e9c25a6"cache-control: public, max-age=300access-control-allow-origin: *access-control-expose-headers: ETag, Retry-AfterPoller
Section titled “Poller”JavaScript
let etag = null;
async function poll(url) { const res = await fetch(url, etag ? { headers: { 'If-None-Match': etag } } : {}); if (res.status === 304) return null; // nothing changed if (!res.ok) throw new Error(`HTTP ${res.status}`); // a 429: wait Retry-After seconds etag = res.headers.get('ETag'); return res.json();}Python
import requests
etag = None
def poll(url): global etag headers = {'If-None-Match': etag} if etag else {} res = requests.get(url, headers=headers, timeout=30) if res.status_code == 304: return None # nothing changed res.raise_for_status() # a 429: wait Retry-After seconds etag = res.headers.get('ETag') return res.json()What resets the cache
Section titled “What resets the cache”The ETag changes only when dataset_version does: on a data change or a
change to how responses are derived. See
dataset_version.
Responses are also cached at the edge for 10 minutes, so a new
dataset_version can take up to 10 minutes to reach every caller. Polling
faster than that re-reads the same response. See
Building on the API for a cadence.