Every consumer of a REST API ends up writing the same code: build a URL, set headers, serialize a body, parse a response, check a status code, retry on the right errors, and turn a 4xx response into something their own application can actually branch on. A team with twenty API consumers gets twenty independent, slightly different versions of that plumbing, each with its own bugs, its own inconsistent retry logic, and its own guess at which errors are safe to retry. A generated SDK exists to write that plumbing exactly once, correctly, and hand every consumer a typed client instead of a URL and a prayer.
Generation only produces something worth using if the API itself gives the generator enough to work with. A generator turning a vague, inconsistently named OpenAPI document into a client produces a client with the same vagueness and inconsistency baked in — a method called `doThing2` because the operation had no meaningful `operationId`, or a return type of `object` because the response schema was never actually specified. The SDK is not a separate deliverable bolted on after the API ships; it is a direct, mechanical reflection of how carefully the API was specified in the first place.
The bar this lesson sets is specific: a good generated SDK should feel indistinguishable from one a thoughtful engineer hand-wrote for that exact API, and the entire discipline of getting there is design work that happens in the API specification, not in the generator's configuration file.
Analogy🏏Cricket
🏏 Think of it like cricket: A translator working from a bowler's post-match press conference into another language produces a genuinely different result depending on what the bowler actually said. A bowler who answers precisely — "I changed my length after the ball started reverse-swinging around the fifteenth over" — translates cleanly into an equally precise sentence in any language, because the meaning was unambiguous at the source. A bowler who mumbles something vague — "I just tried different things, you know" — forces the translator to either guess at the intended meaning or pass the vagueness straight through, and no amount of translation skill fixes that, because the translator can only work with what was actually said. Just as a translator cannot manufacture precision the original speaker never provided, a generator cannot manufacture a clean typed method the original API specification never provided. Just as a well-spoken answer translates itself almost mechanically into any target language, a well-specified API operation generates itself almost mechanically into a clean client method in any target language. The insight is that the quality of a generated artifact is a direct, honest reflection of the quality of the source it was generated from, and blaming the generator for a bad client is usually blaming the wrong stage of the pipeline.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.