Three myths about API design

The gap between knowing this and actually doing it is where most teams lose ground. A few things about API design that get repeated more often than they get checked.

The question is rarely whether something can be built, but what it costs to keep running afterwards. It rarely shows up as a line item, which is exactly why it slips.

“It only matters for big sites”

Consistent naming saves every future integrator hours. The reasoning matters more than the rule, because the rule has exceptions. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

“We can deal with it after launch”

Sometimes true, usually expensive. There is a version of this that is over-engineered, and it is worth avoiding.

“Our platform handles it”

Errors should be as well designed as successes. This is the sort of thing that compounds, quietly, in both directions. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

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

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