API design for small teams

The gap between knowing this and actually doing it is where most teams lose ground. Most advice about API design assumes a team that does not exist at your size. Here is the version that does not.

The question is rarely whether something can be built, but what it costs to keep running afterwards. Budget a little time for it every quarter and it never becomes a project of its own.

What to keep

Consistent naming saves every future integrator hours. The teams that handle this well are rarely the ones with the biggest budgets. If two people in the business would answer this differently, that gap is the actual problem.

What to drop

Process that exists to coordinate ten people is overhead when there are two of you. Getting it slightly wrong is survivable. Ignoring it entirely is not.

How we handle it

Errors should be as well designed as successes. Getting it slightly wrong is survivable. Ignoring it entirely is not. Anything you cannot measure here, you are deciding by taste, which is fine as long as everyone knows it.

What this looks like day to day

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
• Version the API before anyone else depends on it — and you know whether that is true here
• There is a way to tell whether the last change to this helped

If you want a second opinion on how yours is set up, ask.