3 Things to Consider before Versioning your API

The question of how to version your API is one with varied responses depending on who you ask. But, often times we probably jump the gun on this. A couple of things drive API changes and each may require a different approach to handle the scenario. Let’s look at a few

New API Attributes

This is straight forward. You need to add new attributes to your API. Instead of versioning your service all you need to do is make the new attributes optional. The documentation captures this change and your API is backward compatible for older apps or clients. No big deal here.

Attribute Deprecation

This situation is quite different from the first because removing a required attribute will break older clients which you don’t want. This situation requires more of a social solution than a technical solution. Just give your clients a time frame for which the attribute will be supported and communicate it clearly, using documentation, your website and social media.

A combination of this and the first approach can be seen as an expand and contract approach where you may add a new attribute which might replace two other attributes (expand) and then remove the two older attributes at a predetermined time (contract).  These scenarios once again allow you get by without API versioning.

Resource Creation

Maybe the changes you are about to make actually imply a new and different API after all. It could be a new resource created to handle some level of aggregation required in certain scenarios. Which ever the case, new resource creation is what is called for and not API versioning.

If none of these scenarios really meet what you are trying to accomplish it is possible you do need to version your API. Different approaches to doing that will be discussed in separate post. At the very least, it does make sense to pause and reflect on the end goal. What else do you consider before deciding to version for your API?