Best dating introduction
With the advent of Web services, there are some new features that you can take advantage of that can help alleviate the problem, but the brutal fact of the matter is that versioning has not been built into the Web services architecture.” What constitutes “best practices” has evolved over time and is determined by provider choices for their own products, not necessarily from any outside governing body.
So, when it comes to choosing an approach to versioning, there are a wide variety of practices. For many providers of web resource APIs, this is the primary consideration.
When your API has reached the point of expanding beyond it’s original intent and capacity, it’s time to consider the next version.
Whether that next iteration is a whole number version bump or just a feature expansion, it’s important to consider the pros and cons of how you let your developers know about it.
IBM addresses this in their own “Best practices for Web services“: “The correct handling of API versioning has been one of the most difficult issues faced by developers of distributed systems.
This pushes the obligation to refactor code to downstream developers.Once you start taking things away, or dramatically changing what’s in place, it’s time to consider another version.Often, these new versions become whole new products.In either case, products and platforms that rely on an API for core functionality may need a code refactor to adapt.That can be time and resource intensive, so a sane and well documented approach to URI versioning is crucial for multiple stakeholders.