If you want to start a debate among API technologists, just ask them to share their thoughts on "API versions". For sure, you'll find some intense feelings in short order. The term "API version" has become synonymous with "changing the API", and this is the first hurdle in untangling a sensible strategy for supporting ongoing changes to published APIs without causing unnecessary problems for API consumers.
Most APIs don't need versions, what they need is the ability to support compatible changes over time (not such a fancy word, right?) There are many examples of technologies that support compatible changes, such as TCP/IP, HTTP, and HTML . Most programming languages do this too. Successfully implementing compatible changes requires a commitment to support the change, and maintaining that commitment over the long term. It's that simple, but not that easy.
The most efficient APIs that accommodate changes can continue to add functionality without breaking existing API consumers -- even those that were created many years ago. The least effective API changes require all API producers and consumers to rewrite and republish their code every time the API design is updated. The key to success is designing support for compatible changes from the start. With this pillar in place, the process of implementing and releasing compatible versions of your API becomes more consistent, predictable, and resilient over time.
And that's what we all need, right?
Versioning is the "middle finger" to customers.
One of the key challenges of maintaining APIs on the web is dealing with changes over time. Simply put, once you publish your API and people start using it, the interface represents a dependency. Consumers of an API depend on the stability and reliability of the API.
But many times, the team on the server side (the API producer) ignores this dependency. Instead, they simply make changes with little regard for the cost of effort they pass on to API consumers. As Roy Fielding ( REST celebrity) put it in a 2013 tweet :
"...'v1' is a middle finger to your API clients..."
The middle finger from the API producer to the API consumer essentially means, "yes, we changed our API, deal with it". The good news is that it's common practice to start a new version at a new URL -- from api.example.org/v1/customersmoving to api.example.org/v2/customers. At least this isolates the changes to some new branch. But things got worse; these splits