FREE LESSON · Applications & software architecture · 2 OF 4
API Design: Contracts, Errors and Idempotency
An API is a promise over time — Contracts, identity, errors, and idempotency
An API defines meaning, not just fields.
Specify valid requests, authorization, identity, invariants, success, failure, retries, ordering, and compatibility. Stable identifiers should not silently inherit mutable display names. Errors should tell callers whether to correct, retry, wait, or stop. Versioning cannot repair an ambiguous contract.
Design from the caller’s recovery decisions, including the moments when neither side knows whether work completed.
Timeout does not mean failure
A client sends a request; the server commits; the response is lost. The client sees a timeout but the operation succeeded. Blind retry can duplicate the effect; giving up can mislead the user. Operation identity plus a queryable outcome lets the protocol resolve uncertainty.
Distributed APIs need an “unknown outcome” state; collapsing it into failed is dangerous.