Archive / Topic
#API design
8 posts, newest first
Keep read progress separate from dispatch acknowledgement
A reader position helps someone resume a log. An acknowledgement records who has accepted the work
Give a changing list a stable reading point
An API cursor should say what ordering and visibility it preserves while new records arrive
Put the operation key in the timeout response
A timeout can leave a remote command unresolved. Preserve the original operation identity so the caller can reconcile safely
A retry budget should name its final answer
A caller needs a useful outcome when the retry window closes, especially when the remote result is still uncertain
Return the first outcome when an idempotency key repeats
Duplicate suppression is only half the contract; callers also need a stable account of what the original request produced
An idempotency key can expire before its risk does
Retry safety depends on the lifetime of the original side effect, not only the convenience of a short deduplication window
Rate limit headers should describe the next safe attempt
A 429 response is more useful when it tells the caller how recovery actually works, not only that a threshold was crossed
Idempotency needs a published lifetime
The retention window is part of the contract, because replay safety ends the moment the original decision record disappears
Often tagged alongside API design