The Stale Read Surprise
Behind many APIs, a write goes to a primary while reads hit replicas or caches that lag slightly. A client that creates a record then immediately fetches it may get a 404 or stale value. The API must set honest expectations about when a write becomes visible.
Designing for the Lag
- Return 202 Accepted for async writes instead of pretending the work is done.
- Give a status URL the client can poll until the change lands.
- Support read your own writes by routing a user back to the primary or a freshly updated cache for a short window.
Telling the Client
Echo a version or updated timestamp so the client can tell whether it sees its own write. For collections, document that newly created items may take a moment to appear in list queries.
Why Accept It
Forcing every read to the primary destroys the scalability that replicas provide. Eventual consistency keeps the system fast and available; the job is to make the lag visible and tolerable, not to hide it.
Key idea
When reads lag writes, design APIs to admit it with 202 responses, status URLs, versions, and read your own writes, keeping the lag visible and tolerable rather than hidden.