Specs and SDKs — Making the Contract Machine-Readable and the Clients Generated
An API that exists as code, a spec document, hand-written SDKs in six languages, and documentation pages is an API that exists in four slowly diverging copies. The evolution-era answer is to pick one source of truth — the machine-readable spec — and generate or verify everything else from it, so a change made once propagates everywhere or fails loudly. This post is the spec-first pipeline: what it takes, what it buys, and where generated SDKs still need human hands.
One machine-readable source of truth: complete specs, bidirectional conformance tests, dated snapshots per version, and spec-diff breaking-change detection as the evolution linter. Generate the mechanical 80% of every SDK with tolerant-reader behaviors built in; humans keep idiom and the fenced hand-written islands.