Five mistakes teams make with API design

Most teams know this matters. Fewer have decided who owns it. These are the ones we run into repeatedly when we audit API design.

Most development decisions are really maintenance decisions wearing a different hat. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

Where it usually goes wrong

• Treating it as a launch task rather than an ongoing one
• Assuming someone else already owns it
• Consistent naming saves every future integrator hours
• Version the API before anyone else depends on it
• Never checking whether the fix actually worked

Errors should be as well designed as successes. The cost of getting this wrong is rarely visible on the day it happens. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

What to do next

The short version

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Three things worth confirming about API design before you move on:

• Someone can say what the current setup is without going to look
• Consistent naming saves every future integrator hours — and you know whether that is true here
• There is a way to tell whether the last change to this helped

Pick the one that would hurt most if it failed, and start there.