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

mmd notifications at github.com
Sun Oct 20 10:45:30 UTC 2019

I still very much disagree with the overall approach to tightly couple the OSM XML version returned by the API version to the version number that is part of the URL. I found [this blog post](https://www.mnot.net/blog/2012/12/04/api-evolution.html) raises a valid point here:

_Another conversation that I have sometimes is about how to relate format changes to API versions. In short, they should be completely separate; formats can have lives of their own, and to get the most value out of them, they should do so. It’s fine to say “Version 2 of the API requires the foo resource to support version 5 of the bar format,” of course._

Let's be fair, changing the osm version header from 0.6 to 0.7 would cause some breakage for no good reason, where in reality you're maybe only trying to change the HTTP response codes or produce some nice error messages to be returned by the API. In both cases there's no valid reason at all to also change the OSM XML version number.

I still haven't seen an answer to a point I raised earlier on, how the long term evolution of new version numbers should look like, in particular, for how long old versions will be supported. Without a clear strategy in place, you would keep on adding more and more versions over time, to accommodate for API consumers unable or unwilling to move to a newer version. Today, they don't think about "sunsetting" a version, but in the future they will have to, and they need to be aware of that up front. 

Handling multiple versions in parallel will add some mental strain when working with the code, even when  they share a large part of the same code base. Please keep that in mind so the additional complexity won't kill the code in the long run. 

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/20191020/e10c9c9a/attachment.html>

More information about the rails-dev mailing list