How to get API design right
We end up explaining this on discovery calls often enough that it deserved writing down. The short answer to API design is that it is mostly a sequence of small decisions, not one big one.
The question is rarely whether something can be built, but what it costs to keep running afterwards. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.
What it costs to ignore
Consistent naming saves every future integrator hours. It is worth being explicit about, because assumptions differ quietly. Doing this properly once is usually cheaper than doing it approximately three times.
The steps
- Establish what you have today before changing anything
- Version the API before anyone else depends on it
- Errors should be as well designed as successes
- Write down the decision so the next person does not re-litigate it
Errors should be as well designed as successes. In practice this is a scheduling problem more than a technical one. Budget a little time for it every quarter and it never becomes a project of its own.
A reasonable first step
How to tell if yours is fine
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
None of this needs a rewrite. Most of it is a morning's work once someone decides to do it.