API design: the questions we get asked most

Teams tend to reach for this after something has already gone wrong. The questions about API design that come up most often on our calls.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Write the reasoning down alongside the decision, because the reasoning is what changes first.

Do we need to care about this?

Consistent naming saves every future integrator hours. In practice this is a scheduling problem more than a technical one. Doing this properly once is usually cheaper than doing it approximately three times.

Can it wait until after launch?

Occasionally. More often the post-launch version costs several times the pre-launch one. The teams that handle this well are rarely the ones with the biggest budgets.

How do we know it is working?

Errors should be as well designed as successes. Where this goes wrong is almost never a lack of knowledge. The version that survives contact with a real deadline is the simple one.

In practice

The question is rarely whether something can be built, but what it costs to keep running afterwards. 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

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