API design, explained without the jargon

Every audit we run turns up some version of this. Here is API design without the vocabulary that usually surrounds it.

The question is rarely whether something can be built, but what it costs to keep running afterwards. Check it against what you would want a competitor's site to get wrong.

The short version

Consistent naming saves every future integrator hours. There is a version of this that is over-engineered, and it is worth avoiding. Check it against what you would want a competitor's site to get wrong.

Why people complicate it

Most of the confusion comes from tooling rather than from the idea itself. Where this goes wrong is almost never a lack of knowledge.

Version the API before anyone else depends on it. Where this goes wrong is almost never a lack of knowledge. Write the reasoning down alongside the decision, because the reasoning is what changes first.

What to do next

Errors should be as well designed as successes. Where this goes wrong is almost never a lack of knowledge. It rarely shows up as a line item, which is exactly why it slips.

The short version

Most development decisions are really maintenance decisions wearing a different hat. Three things worth confirming about API design before you move on:

• Someone can say what the current setup is without going to look
• Errors should be as well designed as successes — and you know whether that is true here
• There is a way to tell whether the last change to this helped

Worth checking on your own setup before it becomes someone else's problem to fix.