Since you are here interested to read about API versioning, you either are going to build an API and looking at the far perspective of its versioning, or believe your current API version needs to be upgraded. No matter which reason is yours, you are at the right place.
Before starting to answer such questions as when is it time to version my API?, can I avoid it?, and when is it inevitable?, let us first of all dwell on some of API design because it is what defines how great your future API will be.
API Design as Future Versions Determiner
There are many aspects to take into account when planning your API. Along with its maintenance, you should also think about versioning and how to avoid it altogether. Though there will very likely come a time you will face the need for API upgrade, making everything to prevent it from happening will only make your API better.
The point of good API design is to make API agile, lasting and flexible so that it would serve as a platform you can later add on. The more solid it is from the beginning, the longer you will be able to do without versioning.
Why API Versioning Is Bad
It takes much time and costs a lot to build an API, and so does its versioning. Apart from resources squandered, you will also be left with two versions to manage and support. You will have to deal with developer confusion and displeasure, for updating their code or switching APIs does not sound like fun.
In his book ‘Undisturbed REST: A Guide to Designing the Perfect API’, Mike Stowe gives lists of the cases when you should and should not version your API. According to him, it is not necessary to create a new API just because you have done the following:
- Added new resources
- Modified the response
- Switched technologies (Java to Ruby)
- Changed your application’s services
However, it is time to think about versioning your API when:
- You have a backward-incompatible platform change, such as completely rewriting your application and completely changing the user interface
- Your API is no longer extendable
- Your spec is out of date (e.g. SOAP)
Conclusion
The need for API versioning will sooner or later arise. But before the time comes, you can make sure you have done the best preparation by going into your API design with a long-term focus. Remember that an upgrade might cost you reputation, for the changes the new version of your API will bring might leave your API consumers fixing the things you broke.
Heading for being advanced does not work in the world of APIs. It is always better for an API product to have one great version rather than ten new super upgrades.>
