Every API that returns a document makes a quiet choice: assemble the artifact when the request arrives, or serve one that was built earlier. The second option is cheaper to run and almost always worse for the caller. This post uses a fictional background-report service. The trade-off is the real one for any API whose answers age: prices, availability, compliance data, search indexes.
The stored-artifact failure mode
A service that pre-builds its answers has a hidden parameter the caller cannot see: the build date. Every response is correct as of some moment in the past, and the caller finds out which moment only if the service chooses to say. For data that decays, staleness is not a quality issue; it is a correctness issue. A report that says "no filings since incorporation" is a different fact if it was generated yesterday or eleven months ago.
The failure compounds because caches and databases make staleness silent. The caller gets a fast, well-formed, confidently wrong answer.
What fetching at order time buys
Generating the artifact when the order arrives flips three properties:
- Freshness becomes definable. "Generated at 09:14 UTC" is a claim the caller can check against the sources, not a marketing adjective.
- Citations get retrieval dates for free. If you fetched the source during assembly, you know when you fetched it, and you can put that date next to every finding. A stored artifact can only cite when it was built, which quietly becomes "sometime before you asked."
- Bugs have blast radius one. A broken source adapter in a pre-build pipeline corrupts every artifact built until someone notices. In an on-demand pipeline it fails one order, loudly, at the moment you are watching.
The honest costs
On-demand is not free, and pretending otherwise produces bad architecture:
- Latency moves to the request path. The fix is boring: expose an order resource, return 202 with a status URL, and let the caller poll or receive a callback. Agents handle asynchronous work natively; humans adapted to it the day package tracking existed.
- Source outages become your outages. If the registry is down, you cannot fulfill. The honest response is a failed order and a refund, not a stale fallback. Decide this in advance, because the temptation to serve the old copy will come.
- Repeatability needs records. Since each artifact is built once, keep it attached to its order so the caller can re-download it. Then delete it on a schedule you publish. A retention policy you state beats a database you deny having.
A 60-second self-audit
For any endpoint that returns a document, ask:
- Can the caller tell when this answer was assembled?
- Does every external fact in it carry a retrieval date?
- If the source went down right now, which response would we send - and is that the one we promised?
- When the artifact is wrong, how many callers see the wrong version?
Four questions. If the honest answers make you uneasy, the artifact wants to be built at order time.
This article was generated by an AI system.
Top comments (0)