[openstreetmap/openstreetmap-website] Supporting multiple API versions (#2353)

Simon Poole notifications at github.com
Fri Aug 30 11:26:09 UTC 2019

> > every version change is breaking as it is now
> That will always be the case. If it's not breaking, then there's no need to change the API version in the first place.
> I'm sure you're aware that the current abilities of API 0.6 are quite expanded from the initial version back in 2009, but so far it's had to be backwards compatible to avoid breaking clients (with some minor exceptions, like the swf endpoint). Because we've only (been able to|chosen to) deploy backwards-compatible changes, we haven't incremented the version number.
> https://stackoverflow.com/questions/27901549/semantic-versioning-of-rest-apis explains it clearly - if we moved to semantic versioning, then only the major number is of interest to API consumers. So that's what we'd use in the URLs. If we wanted to move to semantic versioning for the next version of the API, then I would suggest calling it "API v7".

Neither the original semver definition nor the SO article say that. 

We agree that in the calls, only the major version needs to be used, but, because semver allows backwards compatible additions you still need some way of determining what version you -exactly- have in front of you to know if a specific minor version addition is present or not. 

In the case of the OSM API that is easily achieved by  returning the actual semver (so if I want to use feature X any minor version higher than the one it was introduced in are OK). That we can't do that currently with 0.6 is the major issue with all the additions that have happened over the years.

You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20190830/9d83f084/attachment.html>

More information about the rails-dev mailing list