The versioning of an API is probably one of the most, if not the most, controversial subject around APIs.

As a newcomer within the API world, I did not get the point directly: having a “v” tag within the URLs of the resources sounded quite reasonable.
But, then, I have been challenged by some of my colleagues referring to the famous quote from Roy Fielding, the guy who invented REST: “What is the best practice for versioning a REST API? DON’T.”

I slightly moved to Roy’s camp, but I was still struggling about finding a practical way to implement his “DON’T”. The explanations I found either promoting backwards compatibility to the extreme, or using HATEOAS as a magic incantation, did not convince me, nor my colleagues from the “v” camp!

Now, I am understanding this “DON’T” probably a bit better. I am thinking about versioning our OpenAPI/Swagger files, as well as versioning the piece of code implementing them, but without bothering our API consumer with it, no version tag, anywhere! I am thinking about using the subscription to our APIs as the key information to route requests to the right piece of software, without asking our client to remember to which version it has subscribed to. DON’T ask twice the same information to your customers!

And, along the way, we may have found a way to unite other “routing” features such as confidence checks, canary release, A/B testing, and maybe more…