Your API Is Now Your Interface

I have spent sixteen years being handed an API and asked to design a screen on top of it. The API was somebody else's decision. My job started after it.

That sequence does not work when part of your userbase is software. If an agent is doing the task, your API is the interface. Nobody sees the screen. The endpoint names, the error messages and the shape of the response are the entire product experience, and they were designed by people who were explicitly not thinking about experience.

What a badly designed API feels like to an agent

Same as a badly designed screen feels to a person, which is the part I did not expect.

Unlabelled options. An enum of integers where nothing says what 3 means. A person deals with this by reading docs. An agent deals with it by guessing, and a wrong guess here does not look like an error, it looks like a completed task with the wrong result.

Errors that do not say what to do. "Invalid request" is the API equivalent of a red border with no message. A person tries again slightly differently. An agent tries again identically, several times, then gives up or does something worse.

Actions that cannot be checked before they are taken. If the only way to find out whether something will work is to do it, then anything irreversible is a trap. This is the one that actually worries me.

The design work that has no screen

This is real design work, and it does not look like design work, which is why it keeps landing on nobody's desk.

Naming. An endpoint name is a label. It gets read, in isolation, without context, by something deciding whether this is the right tool for what it was asked to do. That is exactly what a button label does, and we take enormous care over button labels.

Defaults. Every optional parameter is a default you chose, and defaults are where products express their values. An agent will take your defaults far more often than a human will, because it has less reason to question them.

Confirmation. Deciding which actions should be easy and which should require a second step. On screen we do this with a modal. In an API we mostly do not do it at all, and that gap is where the bad stories are going to come from.

Error copy. Somebody has to write those strings. In most teams nobody does, they accrue.

Who should own this

Not the backend team alone, and I say that with affection for backend teams. They are optimising for correctness and consistency, which are the right things to optimise for and are not the same as legibility.

The change I would make in most companies is small and slightly political. Put the person who writes your interface copy in the room when the endpoints get named. That is it. Not a process, not a new role. One person who thinks about how words land, present at the moment the words are chosen.

I did this on my own products because I am the only person here, so the conversation happened in my head. The version where two people have it out loud is probably better.

The test I use

Read your API reference the way you would read a screen you had never seen. Not as a spec, as a first impression.

Can you tell what each thing does from its name alone. Do the errors tell you what to fix. Is it obvious which calls you cannot take back. If the answer to any of those is no, you have found interface debt, and it is now customer facing whether or not you think of it that way.

Common questions

Does this mean rewriting our API?
Almost never. Most of the value is in error messages, docs and naming on new endpoints. Renaming existing ones costs more than it returns.

What about MCP servers and tool definitions?
Same argument, more sharply. A tool description is read by a model deciding whether to call it. It is a label with consequences, and it deserves the attention you would give to onboarding copy.

Is this just good API design?
Largely yes, and I think that is the point rather than a criticism. The people who insisted on clear naming and useful errors were right for reasons that have now become obvious.

Should designers learn to read API specs?
If your product has an API that agents will touch, yes. It is less intimidating than it looks and it is where a lot of the experience now lives.