docs

Getting started

Auth, keys, and how the platform works underneath — where the data comes from, how it's stored, and why your reads keep working even when an upstream doesn't.

Everything is served from our cache

cheapass stores every response and serves your requests from that cache — never straight from the upstream. So when an upstream is slow, rate-limited, or down, your reads don't break; you just get a slightly staler copy. Stale-but-cheap beats fresh-but-broken.

When an upstream resource is the same for everyone — a public RSS feed, an exchange-rate endpoint, a government dataset — we fetch it once, globally, and store one copy that every account reads. A thousand of you subscribing to the BBC is still one request to the BBC. Your account holds only a lightweight pointer plus your own state (read/unread, tags); we never duplicate the upstream payload per tenant.

Reads refresh on demand — within reason

When you request something that isn't cached yet or has gone stale, cheapass refreshes it on demand and writes the result back to the cache — unlessdoing so would blow the upstream's rate limit, in which case you get the cached copy instead. Either way you get an answer; the difference is just how fresh it is.

…and a scheduled job keeps it warm

We don't wait for a request to refresh. A background job runs on a schedule and refreshes whatever is due, using conditional requests (ETag / If-Modified-Since) so an unchanged upstream costs nothing, and exponential backoff so a flaky one doesn't get hammered. Cadence is tuned per resource — low-velocity feeds refresh roughly every 8 hours.

Today, Feeds runs on the scheduled refresh above (and serves entirely from cache). The on-demand read-through is how the upstream-proxy products — Data, Geo, Events — stay fresh per key. The principle is the same everywhere: store it, serve from cache, refresh politely.

What this means for you

  • —Reads stay up even when an upstream is rate-limited or down.
  • —Shared data is fetched once for everyone, so you're never the reason an upstream blocks us.
  • —You get the freshest copy we can responsibly serve — on-demand when it's cheap, cached when it isn't.
  • —Your per-account state (subscriptions, read/unread, tags) is isolated and encrypted; only shared upstream data is global.