Software Architecture · Cluster
API Design
Contracts, evolution, and compatibility.
- 01 Where an API Contract Ends and the Implementation Begins Which parts of an HTTP exchange callers may depend on, which are incidental, and why undocumented behaviour still turns into a maintenance obligation.
- 02 Idempotency Keys and the Retry Window for Writes How a client-supplied key turns a retried POST into a single effect, what the server has to store to honour it, and where the guarantee quietly expires.
- 03 Pagination Contracts and Why Cursors Drift Less Than Offsets How offset and keyset pagination fail under concurrent writes, what a cursor must encode, and which stability guarantees an API can honestly promise.
- 04 Versioning Strategies and What a Version Number Promises How path, header, and media-type versioning differ in what they can express, why a version is a support commitment rather than a name, and when a new version beats a compatible change.
- 05 Tolerant Readers, Unknown Fields, and the Cost of Strict Decoding How clients should handle members and enum values they do not recognise, why strict decoding turns every addition into a breaking change, and where tolerance turns into silent corruption.
- 06 Deprecation Windows and the Gates That Must Close Before Removal How to announce an end date, measure who still depends on an interface, and sequence soft warnings, hard failures, and deletion so that removal is boring.
- 07 Error Contracts: Problem Details, Stable Codes, and Retry Semantics How to design an error payload that machines can branch on and humans can act on, and why retryability belongs in the contract rather than in the status code alone.
- 08 Schema Evolution and Wire Compatibility Across Formats Why a field number rather than a name is a message field identity, how wire types constrain which retyping is safe, and how Avro resolution differs from Protobuf evolution.
- 09 Consumer-Driven Contract Testing and the Cost of Many Consumers How consumer expectations become executable contracts, what verification proves about a provider, and why the pattern needs a broker and a deployment gate to be worth its cost.
- 10 Breaking Change Detection in API Descriptions Which schema-diff findings are genuinely breaking, which are noise, and why the baseline has to be the released description rather than the previous commit.