Blog
Deep dives on API governance, drift, ownership, and what changes when the heaviest reader of your APIs is an agent. Written from the trenches, not the megaphone.
An API exists so that the consumer doesn't have to understand the system behind it. That only works if the contract carries the abstraction, and across 957 public specs it mostly doesn't: 69% of the last changes say nothing a consumer could act on, and 278 specs aren't at the address they were published at.
ReadA practical walkthrough: get your specs in from GitHub or the CLI, put them under governance, register who consumes them, and make them queryable by your agents.
ReadEvery internal tool now has a class of user that cannot see a screen. The CLI, long treated as the fallback interface, is the one they can operate, and most CLIs were never built to be operated.
ReadHow many APIs do we have, which are healthy, where is the coupling risk? The questions a director should read off a screen are instead answered by asking around.
ReadHanding an agent the whole spec so it knows one endpoint is the wrong unit of work: you pay for the entire document on every turn, and the copy is a snapshot the moment you paste it.
ReadA mock exists to unblock the people waiting on your API. The moment you maintain it by hand it becomes a second source of truth, and the people building against it are building against a fiction.
ReadOwnership pinned to a person is a fact with an expiry date. The first reorg, the first resignation, and the record of who owns what is quietly wrong.
ReadNothing forces a spec to change when the code does, and nothing breaks when it doesn't, so the document quietly stops describing the API while everyone keeps trusting it.
ReadEvery API governance failure I have watched up close comes back to one missing fact: the list of who depends on the thing you are about to change.
Read