What to ask your agency about API design

Most teams know this matters. Fewer have decided who owns it. If you are briefing an agency or a freelancer on API design, these questions are worth asking early.

Most development decisions are really maintenance decisions wearing a different hat. If it only works because one person remembers to do something, it does not work yet.

Questions worth asking

• Who will actually do this work, and have they done it before?
• How will we know afterwards whether it worked?
• What happens if it needs changing in a year?
• What are you assuming that we have not confirmed?

What a good answer sounds like

Consistent naming saves every future integrator hours. The reasoning matters more than the rule, because the rule has exceptions. If it only works because one person remembers to do something, it does not work yet.

Errors should be as well designed as successes. None of that requires a large budget, only a decision and someone to own it. If two people in the business would answer this differently, that gap is the actual problem.

How to tell if yours is fine

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
• Errors should be as well designed as successes — 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.