What to ask your agency about API versioning

It comes up on almost every project, usually later than it should. If you are briefing an agency or a freelancer on API versioning, these questions are worth asking early.

Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. It is the sort of thing that looks like polish right up until it costs you an enquiry.

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

Version before anyone external depends on you, not after. The cost of getting this wrong is rarely visible on the day it happens. Doing this properly once is usually cheaper than doing it approximately three times.

Publish a deprecation timeline and actually honour it. None of that requires a large budget, only a decision and someone to own it. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

In practice

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. Three things worth confirming about API versioning before you move on:

• Someone can say what the current setup is without going to look
• Version before anyone external depends on you, not after — 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.