This is part of a multi-part series on how to version your API.

We are talking through the various ways you can version your API and today are considering using integers.

Keep it simple

Using a plan integer for your versioning such as 2 or v2 is probably the most common and straightforward way to version your API.

The pros: Your clients will be used to it, it is easy to put in your URL if that's where you would like to represent it, it's easy to gauge where you are in an API's version history, and there is just something satisfyingly simple about an integer to represent something that can be incremented.

The Psychology of it

I cannot tell you how many mature APIs I have seen that are still on version 1 and find it difficult to get to version 2.

In one sense, it can be reassuring to see /api/v1 in the URL and feel a sense of stability as the implementing client. It can also feel tempting as an API engineer to batch up your growing list of desired changes together; the client will already be in the code making changes anyway, right? What is wrong with adding one more change to the list?

The problem is that thinking can lead to huge version changes which can feel like an insurmountable weight on both sides. Like a huge PR that keeps getting bigger and bigger, the load of implementing a major version change can be overwhelming and cause the effort to collapse under it's own weight. As a client, it can be intimidating if you see an API sit dormant for a few years then see a major announcement for V2 of the API that you now have to upgrade to.

There is nothing inherit about using integers that forces you to overly-batch changes of course. You can increment forever and as often as you like.

But there are other strategies such as date-based versioning that can arguably be more desirable for rolling out small, manageable changes to your API. That will be the subject of our next blog post.