Skip to content

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/patterns
HTTP/2 304
etag: "e9c25a6"
cache-control: public, max-age=300
access-control-allow-origin: *
access-control-expose-headers: ETag, Retry-After
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()

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.