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

Andy Allan notifications at github.com
Wed Oct 23 10:32:25 UTC 2019

> to tightly couple the OSM XML header version number to the version number that is part of the URL

But these are, and always have been, the same number. The number in the response *is* the API version number, full stop. There's no such thing as an "OSM XML header version number" as an independent concept as you are describing, one that provides a "format version" that could stay the same as the API behaviour and version number changes.

Consider the "api/X/gpx/1" response. Every time the API version number changed, the number in the trace response changed, even when there's no other change in the XML. Therefore that number is the API version number, and not some independent "XML format version" which just happens to be 0.7 too.

Anyway, this is not a new concept being introduced by this PR, so I'm going to try to avoid debating it further here. Perhaps there is a need for a "OSM XML format version" (or, as previously discussed, an "OSM data model version", which is a third distinct concept), but that would be separate from the API version currently contained in the responses.

> changing the OSM XML version header from 0.6 to 0.7 would cause some breakage for no good reason

Given that we haven't decided what the final list of features are in the next version, it's a bit premature to say that it's going to be for "no good reason"!

One of the points of this PR is to introduce a mechanism that allows us to implement whichever changes we see fit, independently of when they are deployed, by using a "feature flag" concept. That way we can implement a bunch of different improvements, and it gives us flexibility to decide when enough things are implemented to make the deployment of 0.7 "worth it". Until that point, it all lives behind the `Settings.deployed_api_versions` flag.

Also, in reality few things are going to break when 0.7 is released, since they can keep working with 0.6. Again, one of the purposes of this PR is to allow us to run multiple versions side by side. So no clients will talk to 0.7 until the developers make them compatible with 0.7.

For software that is consuming OSM data without interacting with the API (e.g. osm2pgsql), sure, some of them wouldn't understand today what to do with e.g. an osm file saved from a `api/0.7/map` call. But that's fine, since we haven't decided what changes there will be yet! By the time we finally release 0.7, those changes could be either trivial or non-trivial to adapt to, and most software will either be adapted already, or users can get their data from a 0.6 source (e.g. `api/0.6/map`), or run it through an `osm07to06` utility, which for some elements like nodes/ways/relations might be a noop, or for notes/traces/changesets might be non-trivial. Who knows yet?

So we'll need to see at that point whether it's for "no good reason" or not, it's not something I can decide on before we've even started implementing anything.

>  for how long old versions will be supported.

As Paul says, "that depends". I'm not going to debate here how long to keep 0.6 running after 0.7 is released, since at this rate we're never going to see 0.7 in the first place! 

> 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.

Absolutely, that's a big factor I considered while implementing this PR. If you have any comments on the approach used in this PR, I'd like to hear them. I'm very much open to suggestions as to how to streamline having multiple versions in the codebase. I'm happy with the current approach but alternative suggestions are valuable.

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/20191023/ecbab84b/attachment-0001.html>

More information about the rails-dev mailing list