API Contracts & Versioning
Rule: an API is not an endpoint, it is a promise you cannot withdraw. Internal code can be
What changes once a call can cross a network and fail halfway.
View all tagsRule: an API is not an endpoint, it is a promise you cannot withdraw. Internal code can be
Rule: an API manages the lifecycle of resources; it does not expose your actions or your tables.
Rule: when the answer does not exist yet, do not pretend the request can return it. Model the
Availability is arithmetic before it is architecture. The arithmetic is worth doing first, because
An estimate is not a prediction. It is a filter: a way to find out, in two minutes and before
CAP is the most cited and most misquoted result in distributed systems. The popular version —
Rule: a dying dependency needs to be isolated, not attacked with more requests. Breakers stop
Rule: agreement requires a majority, not a coordinator. Any scheme where a single node decides —
A consistency model is a contract about what a read is allowed to return. It is not a quality
Rule: failure is the default state, not the exception. Large systems are not designed for the
Rule: ACID stops at the database boundary, and "localhost is a great lie." Across services you
Rule: storing state answers "what is it now"; storing events answers "how did it get there".
The point of knowing these is not recall for its own sake. It is being able to reject a design in
Rule: a list endpoint is a cost-control mechanism first and a feature second. Unbounded
* Network messages can be delayed, reordered, or lost.
Rule: without a limit, one client's mistake becomes everyone's outage. A rate limit is not
Rule: a replica is a different point in time, and a shard key is a decision you cannot undo.
Rule: "eventually consistent" is not a promise you can hand a user. Each read path has to
Rule: a healthy service plus a healthy service does not equal a healthy system. The network
Rule: retry without idempotency is not error handling — it is a bug. And a retry that fires
VSR is a state machine replication protocol designed to keep a group of replicas consistent even when some fail. It
Rule: sending a webhook once is not delivering it. Without signatures, retries, and a way to