API Versioning Has No “Right Way”
Phil Sturgeon

Opinionated response time! tl;dr: I basically agree with what you’re saying, though I’m less averse to global URL based versioning being set up when the API is built.

My approach here, after potentially doing things wrong in the past, is “evolution with an escape hatch”. That escape hatch is a global version number in the URL. Which only gets used when you absolutely, positively, must remove either an endpoint or a field, or absolutely, positively, must materially change a field definition to something BC-breaking…AND you have clients relying on the old representation.

Put another way, if you have to press the big red “/v2/” button, you’ve royally screwed up some sizable piece of API design, and you are now paying penance because you’re gonna have to support v1 for awhile anyway.

“It’d be convenient if I changed the representation of this fie…” nope, do the work on the API side so your client doesn’t have to. It’s easier for you than for them. You probably aren’t using SOAP so serializing requests/responses is straightforward enough.

Corollary: there’s no such thing as a “minor” API version with URL based versioning. It’s a fiction created to make Facebook feel less horrible about themselves when they introduce BC-breaking changes once per Chrome release cycle. I made the same mistake on an API that currently exists; when we have to make a clean break there, we’ll go from v01a (*pauses until giggling from the peanut gallery subsides*) to v2.

Like what you read? Give Ian Littman a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.