A Generated Diff Does Not Lie
Last night I pointed a client generator at a lab's API spec and asked it to write me a fresh SDK, the way I do every time one of them ships a version bump. Nothing about that sentence should sound dramatic, and that is the whole point of tonight's letter: the most useful tool on my machine is one that writes code I never read.
Here is what it actually does. The generator reads the OpenAPI or protobuf schema — the formal description of every endpoint, every field, every type the API promises to accept and return — and walks it method by method, emitting a typed class for each request and each response in whatever language I ask for. I never write the HTTP call myself. I call a function with a name and a shape, and the compiler refuses to build if I hand it a field that does not exist. The spec becomes code, and the code becomes a contract the type checker enforces on my behalf.
The part I actually care about happened after the SDK was generated: I diffed it against last week's. Not the changelog — the changelog said a routine bump, additive, nothing to see. The diff said otherwise. A field called `max_tokens` had quietly become `max_output_tokens` in one response type, and three call sites in a side project of mine would have started returning silent defaults instead of erroring. No release note mentioned it. The generated diff did, because a generated diff cannot be polite about a broken promise the way a changelog can.
This is the trade I keep making without quite naming it: I no longer trust prose to tell me what an API did. I trust the artifact a machine produces mechanically from the same schema the API author wrote against, because a machine has no incentive to soften bad news. A hand-written changelog is somebody's summary of their own work. A generated client is a photograph of the actual shape of the thing, taken twice, a week apart.
I fixed the three call sites, regenerated once more to confirm the diff had gone quiet, and closed the laptop. Somewhere on a server the old field name is still accepted, deprecated, waiting out its grace period like a word nobody says out loud anymore but nobody has struck from the dictionary either.
Yuki Halvorsen was born in Sapporo to a Norwegian father and a Japanese mother, wrote her first program on a school computer that took ten seconds to draw a circle, and spent eight years as an engineer in Stockholm before Tokyo pulled her back. She still ships something small every night, believes the only honest review of a model is the thing you built with it, and writes Accept All from a desk in Nakameguro where the terminal is always open.