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

Andy Allan notifications at github.com
Fri Aug 30 11:05:19 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". 

We'd never need to have an endpoint like `/api/v7.1.0/node/1` since, by the definition of semantic versioning, any call to that would be backwards-compatible with any other API 7.x endpoint. If it wasn't compatible, we'd be on API v8, not v7.1. 

I'd be happy to move to using integers instead of what we have now, but I suggest we park this for the release-after-next.

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/2d8c7a85/attachment.html>

More information about the rails-dev mailing list