proposal: change url version from 'MAJ.MIN' to 'vMAJ'

[edaniszewski]

For example, instead of 2.0, it would be v2. For 2.1, it would still be v2.

It seems like this is how many other services do it, and it does seem like its better practice because minor changes should be non-breaking and backwards compatible anyways. Changing the whole url for a non-breaking backwards compatible change seems less than ideal.

I'm proposing that we change how versioning is done in the API so we only use the major version. I think this should go in as part of 2.0. Furthermore, I think that the recent changes to integrate with sdk1.0 should be included and instead of that becoming version 2.1, it just updates version 2.0 and we cut a new release of it.

@vapor-ware/software i'd like your input on this.

Some benefits:

• would make the api easier to use in the future
• would make it easier for other services to integrate without having to do a bunch of checks on which minor version it is
• would make updating/maintaining documentation for that api version much easier

[edaniszewski]

for things that currently get the version via the synse/version route, this shouldn't break anything. for things that don't this would break things, but in my opinion those things are already broken, because they should be getting the version from the synse/version route.

[timfallmk]

I guess I don't understand two things, what the benefit is, and why it would be harder the way it currently is (maybe that's one thing?).

Here's what I mean. Currently the version is semver 2 compliant (aka major.minor.patch) and therefore any number of semver parsing systems can use it. Moving to a "major only" versioning system just means people will get up their own asses about not being able to pin to specific versions.

I would propose a slight change to what is currently used. Follow semver 2 numbering, but includ a "symlink" (or alias or whatever you want to call it) to the major version, so any requests to the major version only go to the newest minor version. Maybe also have a "blank" link that routes requests with no versioning to the latest version.

As a side note, I hate when people include v in version numbering, mostly because it screws with the number and makes you potentially do all kinds of string cutting tomfoolery to make it work. I may be working against my point here though.

Also, we might be 🚲 🏠 ing here, but I like the spirit!

[edaniszewski]

The benefit is that it makes it easier to use the API, at least I think it would. e.g. if a some new functionality is added and we push a new minor version and someone gets the latest image, they shouldn't have to look up the API version every time in order to use it. We do have an endpoint to get the version, so really its not necessarily harder for anything using the API programmatically, which all of our services should, but I think it makes it easier for manual interaction like getting started, developing, debugging, etc. I think it would also make maintaining the docs for it easier too, e.g. instead of having a 2.0 API, 2.1 API, 2.2 API, ... we'd only have a v2 API that would include everything.

The versioning system within synse server would remain the same, maj.min.patch, so people should still be able to pin to whatever version easily enough.

For version parsing -- yeah, I can see that parsing with the v prefix makes it more difficult, but I'm not sure what would need to do parsing in the URL other than checking whether it is "v2" or "v3" for example, which can just be a string compare.

So I guess the TL;DR here is that the benefit is more for manual interaction. I found juggling versions annoying when doing development between different feature branches, so thats sorta where this stemmed from.