A public API has clients that poll an endpoint every minute looking for changes. How would you design that endpoint and its rate-limit policy so polls that find nothing new are cheap for both sides?

## The problem Polling is the default integration pattern because it needs no inbound connectivity from the client. Its cost profile is brutal: with N clients polling every 60 seconds, the origin pays N requests per minute forever, and the overwhelming majority discover nothing has changed. The design goal is to make the "nothing changed" answer as close to free as HTTP allows, and to make the cheap path the one clients are incentivised to take. ## Make the negative answer cheap on the origin A 304 saves bandwidth automatically. It only saves origin CPU and database work if the handler can decide "unchanged" without producing the representation. That requires a validator whose source is a single cheap read: - a per-account or per-tenant **change sequence** bumped by every mutation (a counter column, or the latest event id from an outbox); - or `max(updated_at)` plus a row count, which also catches deletions; - never a hash of the serialized payload, because computing it means you already did the expensive work. The handler flow becomes: authenticate → read the sequence → compare with `If-None-Match` → return 304, or else build the response. Now an unchanged poll is auth plus one indexed lookup. ## Make the validator stable A validator that churns turns every poll into a 200 and makes things worse than no validator at all, because you have added bytes and complexity. The usual culprits: a `generatedAt` or `serverTime` field in the body, a per-request trace id echoed into the payload, non-deterministic ordering from a set or a map, floating-point formatting differences between instances, and pagination cursors that encode a timestamp. Determinism of serialization is a hard requirement, and it deserves a test: fetch twice with no writes in between and assert the validator is identical, including across two different server instances. ## Align the rate-limit policy with the behaviour you want Quota is the lever that changes client behaviour. The widely copied model is: conditional requests that result in `304 Not Modified` do not consume quota. The economics then favour the well-behaved client — it can poll frequently without ever exhausting its limit — while a client that ignores validators pays for every fetch. Complementary signals: - a header advertising the recommended minimum polling interval, which the server can raise dynamically when a resource is quiet or the platform is under load; - standard quota headers so clients can self-throttle; - `429` with `Retry-After` for clients that ignore all of the above. One caution: making 304s free is an anti-abuse decision as well as an efficiency one. The request still costs TLS, routing and an authenticated database read, so "free" must be bounded — typically by a separate, much higher ceiling or by connection-level limits — or a client can poll in a tight loop at zero quota cost. ## Shape the resource for polling Polling a large collection to detect a small change is wasteful even with 304s, because the moment anything changes the client downloads everything. Better resource design for change detection: - a **change feed**: `GET /events?since=<cursor>` returning only what happened after the cursor, so the transferred volume is proportional to actual change, not to collection size; - a **lightweight summary resource** ("latest version" or counts only) that clients poll cheaply, fetching the full resource only when the summary moves; - stable, deterministic pagination so a changed page does not cascade into refetching every page. ## Offer an escape from polling For clients that can accept inbound calls, webhooks or server-sent events remove the poll entirely and cut change-detection latency from the polling interval to near zero. The realistic platform position is to support both: a change feed with conditional GET as the universal fallback, webhooks as the efficient path, and a documented, enforced polling etiquette in between. Publish the expected behaviour — send `If-None-Match`, respect the advertised interval, back off on 429 — as part of the API contract, because integration code written once will run unchanged for years.