Before you invest in API design

Every audit we run turns up some version of this. Before you spend anything on API design, it is worth confirming a few things are already true.

Most development decisions are really maintenance decisions wearing a different hat. Assume whoever inherits this will have half your context and none of your patience.

Prerequisites

• You can describe the outcome you want in one sentence
• Someone owns it after the work is done
• Consistent naming saves every future integrator hours
• You have a way to tell whether it worked

Warning signs

Version the API before anyone else depends on it. Where this goes wrong is almost never a lack of knowledge. The version that survives contact with a real deadline is the simple one.

Errors should be as well designed as successes. None of that requires a large budget, only a decision and someone to own it. The version that survives contact with a real deadline is the simple one.

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 any of that sounds like a description of your current setup, it is fixable.