An untested API example is just a guess

A curl command can be perfect and still be a lie. Clean syntax, the right endpoint, every parameter where the spec says it should be, a response body with all the fields you'd expect. None of that tells you the request actually runs.

This is one of the things you learn when you start documenting APIs: An example that looks right is different from an example that actually works. If you're not careful, it's now easier than ever to fool yourself and your readers. Hand a model an OpenAPI document and it will give you a flawless-looking request and a realistic response in a couple of seconds, without ever touching the API.

So I've settled on a rule for myself: an API example is something you run, not something you write. If I publish a request, I want to have watched it work.

The spec gives you the contract, not the experience

An OpenAPI spec is a good place to start. It tells you the endpoint exists, which method it accepts, what's required, how auth works, what the body should look like, which responses are possible. That's real information and I'd never skip it.

But reading the contract isn't the same as using the thing. A spec can be technically correct and still leave the developer's real questions open: What does a realistic request look like, as opposed to a schema-shaped one? Which parameter combinations actually work together? Is a field that's optional on paper required in practice? Those are documentation questions, and no amount of staring at the schema answers them. You have to make the request.

How I actually build one

My process isn't clever. Start with the spec and work out what the operation is meant to do. Build the request in something like Postman. Send it to the real API. Look at what comes back. Then start breaking it on purpose: drop a parameter, change a value, force the error, and check whether the response matches what the spec led me to expect. Only once I've done that am I willing to turn it into a published example.

That last part is important because it can uncover something worth documenting. The API might return a field the spec never mentions, or an error message more helpful than the happy path. A parameter description might be accurate but easy to misread. The payload in an internal doc might be a year out of date. Or the request might work only when you include a detail I'd have called cosmetic. You don't catch any of that by reading. You catch it by sending.

The part that's really verification

There's a version of this job that's basically translation. Take the spec, turn it into prose, add a request, add a response, ship it. Sometimes that's genuinely enough.

But for developer-facing docs, I think the more honest description of the work is verification. The questions that matter aren't about phrasing. Does the operation behave the way we claim it does? Can a stranger follow the page from "I want to do X" to a working request? Do the examples work reliably? Are the assumptions buried in the implementation visible on the page, or only to the person who wrote the code? Framed that way, the docs stop being a layer of text sitting on top of the product and start being part of how the product feels to use.

Why AI makes verification matter more

AI is genuinely good at the shape of an API example. Give it the spec and it will produce the request in curl, JavaScript, Python, whatever you ask for, and it saves you the mechanical work. I use it for exactly that.

The catch is a new kind of failure: an example that's completely convincing and never once executed. The better these tools get at producing plausible output, the more important it becomes to distinguish what looks plausible from what has been proven to work.

And this is where API docs have an advantage most AI-assisted writing doesn't. A wrong fact in a research brief is formatted exactly like a right one, and nothing goes red. An API example isn't like that. There's a real service on the other end that will accept your request or reject it, and that's a test you can run in a minute. Failure gives you a concrete signal. You just have to trigger it. So if an AI hands me a request it never sent, I treat it as a draft. If it hands me a response that didn't come from the API, I treat it as fiction. The output isn't worthless. It just hasn't passed the part that matters.

Working software deserves working docs

A good API example should lower the reader's uncertainty. They copy it, swap the obvious values, run it, and get something close to what the docs promised. That's a harder standard than "looks right," and it changes what I count as quality. A clean paragraph and a realistic-looking response are both nice to have. But if the developer runs the request and it fails, neither counts for much.

Working software deserves working documentation. And if that documentation ships API examples, those examples should earn the same skepticism I'd apply to code. Until someone has run them, they're guesses in a nice font.