How do I version my API?

Almost every enterprise application needs integration with one or more external systems. Different systems talk with each other using a set of well-defined APIs. However, as the system grow, you might be adding/removing/modifying the existing functionality. In this case, you need to be careful so that you don’t break the other system that might be using your APIs.

In order to tell the outside world that something has changed, we release different versions of the API. But how do you manage the versioning? Are your versions meaningful to the users? Do they convey an important message?

Semantic Versioning

Personally, I feel that you should be using Semantic Versioning (SemVer in short) if possible. Semantic versioning has been developed based on the existing notions of API versioning and addresses many problems efficiently. Below are some important points that define Semantic Versioning.

  1. The version number follows the convention MAJOR.MINOR.PATCH (example 1.3.2)
  2. Do not add preceding zeros to the versions. For example, doing 01.03.10 is not correct. This could easily lead to confusion.
  3. During initial development, keep the MAJOR version as 0. For example 0.1.1
  4. Once the first version is released, make it as 1.0.0
  5. Keep all the numbers nonnegative.
  6. The PATCH version must be incremented only if you make backward compatible bug fixes.
  7. The MINOR version must be incremented if you make backward compatible changes. This might also include introducing new features.
  8. When you increment the MINOR version, reset the PATCH version to 0.
  9. The MAJOR version must be incremented when you make backward incompatible changes. Reset MINOR and PATCH version when you do so.
  10. You can have additional labels for pre-release and build metadata are as extensions to the MAJOR.MINOR.PATCH format.