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

We've heard a lot of questions about whether to consider Semantic Versioning for your API. Below we talk through what is Semantic Versioning and whether it works for your API.

What is Semantic Versioning?

Semantic versioning is the standard for versioning in just about everything in software. Here's what it looks like:

2.3.1

In that case, you are on the 2nd major version, the 3rd minor version, and the first patch.

What's the difference between major, minor, and patch?

You can see the full write up here but generally changes that are incompatible with with the previous version i.e breaking changes are represented by incrementing the major version. For example, if you change how authentication works and API clients will need to make a necessary change on their end, you should represent that change by incrementing the major version number.

Changes that add new functionality in a backwards compatible way such adding a new endpoint can be considered a minor change and only require incrementing the minor version.

What about the patch? Well if realize a you have a bug and need to fix it, that fix should be represented as a patch.

Should I use it?

While Semantic Versioning is extremely common in software, particularly for versioning packages, many see it as a little much for versioning your API. The reasoning is that API clients only really care about breaking changes and therefore any minor changes or patch changes do not warrant a new version. For example, the introduction of a new endpoint or a bug fix is non-breaking and might make your versioning "noisy." Instead, they might recommend simple incremental versions such as /api/v2/users.

That is not to say you can't use semantic versioning. Many including Google endorse it as their preferred versioning style. However, my personal recommendation is for a simpler single version strategy or a calendar based style.