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…
High impact blog posts and eBooks on API business models, and tech advice
Connect with market leading platform creators at our events
Join a helpful community of API practitioners
Can't make it to the event? Signup to the Nordic APIs newsletter for quality content. High
impact blog posts on API business models and tech advice.
Become a part of the world’s largest community of API practitioners and enthusiasts. Share your insights on the blog, speak at an event or exhibit at our conferences and create new business relationships with decision makers and top influencers responsible for API solutions.