I’ve been writing and talking about API contracts and versioning since a long time.

Here I have presented on The Developers Conference about API contracts break and versioning. I have presented strategies for versioning your API, which is a good introduction to the subject.

However I didn’t talk about how to actually organize your versions in a semantic way. I decided to write this short post to present the importancy to identify how the new version you are releasing is impacting your consumers.

Here the Semantic Versioning comes to the game. It tells us how to identify from breaking changes until the minor patch you can do just looking at the version. It’s all about communicating the consumers the intention of the version being released.

Your versions will follow the pattern MAJOR.MINOR.PATCH.

And the versions will be incremented as below:

  1. MAJOR: identifies a breaking change.
  2. MINOR: identifies a new functionality that doesn’t include a contract break because it’s backward compatible.
  3. PATCH: identifies minor bug fixes that still are backward-compatible.

That’s all for this post, for more information, you can access the semver’s official website. Feel free to ask questions and discuss the subject.