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

Andy Allan notifications at github.com
Wed Sep 4 13:02:21 UTC 2019

> you are essentially making an argument for versioning the representation too.

No, I'm explaining that the `version` is the API response version, not a version of the data model. For example, nothing changed in the `trace` responses when we last changed the API version, but the responses to `api/0.6/gpx/nnn` are all `<osm version="0.6">` and not 0.4 or 0.3 or whenever that part of the underlying data model changed. So in API 0.7, if they have the same underlying data model, or even the same representation, they will definitely have 0.7 in their responses.

 So I'll say it again, the `version` in the documents indicates the version of the API used, not the version of any underlying data model.

> Up to now the abstract underlying data representation has essentially been documented (if you so want) by the XML representation and has been in lock step with that.

No, it hasn't. There's been lots of changes to the underlying data model in the last 10 years, none of which have had a change in API version number - because even though the data model has changed, the API request/responses have only changed in backwards compatible ways. For example, we added notes. That was a backwards-incompatible change to the data model (you can't fit notes into a database that doesn't have a table for them, for example) but a backwards-compatible change to the API, hence no version number change.

> And for example it would be -very- surprising if implementing #2348 and jacking up the API version

Nobody has suggested that adding a new backwards-compatible API call needs a new API version - except for you, when you wrote "Without it (this PR) we would have simply added them as a 0.6 feature". So I'm not going to rebut something of your own creation that you are now arguing against. 

If you have another example, that would be helpful.

> if the gratious change to the "representation version" hadn't been made.

I'm not proposing any "gratuitous" changes to the API version. The only reason I'm proposing to change the API version is to allow us to make backwards-incompatible changes that can't otherwise be made. The whole point of this PR is to allow us to run multiple API versions in parallel - it's even in the title! So any tools that can only parse one version can keep using that version. Gratuitous change would be to yank the old version when the new one is deployed, or to bump version numbers for backwards-compatible changes, and I'm proposing neither of those.

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/20190904/a96fa3b7/attachment.html>

More information about the rails-dev mailing list