Semantic version of REST apis?

Question

I appreciated several version control schemes for REST apis (header, url, ...). By far, the most reliable approach is the url option: it works with proxies and does not rely on obscure schemes such as dates for versions .

Now, when I look back, everyone who uses the URL-based approach uses versions like v1 , v2 , etc. No one uses minor versions or even schemas such as semantic versioning .

A number of questions arise:

• When do you increase the version number of the REST api (surely you have more updates for it than every five years)?
• If you have a bug fix, you probably are not increasing the version number, but how do you differ in both versions?
• If you use a very small-scale approach, you get many versions that you need to place in parallel. How do you deal with this?

In other words: how does a company such as GitHub, for example, have only v3 today (2015), when they have already been in business for 7 years? Does this mean that they actually only changed their api twice? I can not believe this.

Any clues?

Answer 1

The main version number is all you need for the web service. Since your consumers are only concerned about backward incompatible changes, and (if you are doing semantic versioning correctly), they will only be introduced after the release of a new major version.

All other changes (including new features, bug fixes, bug fixes, etc.) should be "safe" for your customers. These new features should not be used by your consumers, and you probably will not want to continue to run this disjoint version containing an X or Y error for longer than necessary.

Using the full version number in your URLs (or any other method that you use to control the version of the API) actually means that your consumers must update the URL of your API every time you make an update / patch for your API , and they will support using an unsupported version until they do.

This does not mean that you cannot use semantic versioning inside, of course! Just use the first part (main version) as the version number for your API. It just doesn't make sense to include the full version number in your system URL / header / other versioning.

So, to answer your question: you update your API every time you create a new version, but you only release a new version of the API when you have a new major version. Thus, you only need to post several different versions (and you can, of course, abandon older versions over time).