[openstreetmap/openstreetmap-website] Capabilities call and versioning (#2162)

[Andy Allan]

> We currently use the unversioned [capabilities] call ...
> ..., changing [the capabilities call] would clearly need a new API version,

Yeah, this is where it gets a bit of a logjam, since the unversioned call is, by definition, unversioned!

Can we assume the following?

* There needs to be an unversioned call of some sort, in order to establish which API versions the server offers.
* The client should then request a versioned capabilities document. This could contain different information for different API versions (e.g. if tracepoints were renamed foopoints, etc).

If so, I would conclude that:

* Everything else in the unversioned capabilities call - other than which versions are supported - is unnecessary and uncertain, since it e.g. might correspond to features that have different names in different versions.
* The version element (e.g. `<version minimum="0.6" maximum="0.6"/>`) in the versioned capabilities call is both unnecessary and uncertain, since that call is supposed to describe the capabilities of that particular version of the api
* Also, the current way of describing available versions is insufficient, since it only gives two options (maximum and minimum) and doesn't describe which, if any, intermediate versions are supported (e.g. we make some trivial mistake in 0.7, and end up with 0.6 and 0.8 available and 0.7 removed).

So my proposal would then be:

* Leave the current unversioned capabilities call as-is, for backwards compatibility, and change only the maximum attribute of the  `<version>` entity. 
* The original question (what goes here in `<osm version="???" ...>` for the unversioned call) will be left as `0.6`, again for backwards compatibility.
* The api/0.6/capabilities call will be left as-is, including the `<version>` entity, since it's not clear that changing the maximum attribute here makes any sense anyway but it's best to leave it in, for backwards compatibility.

* Create a new unversioned call (api/versions) which returns only a list of available versions and no other information. That document will itself be unversioned, e.g.

```
<osm generator="OpenStreetMap server" ...>
  <api>
    <version>0.6</version>
    <version>0.7</version>
  </api>
</osm>
```
* In the `api/0.7/capabilities` call, no `<version>` element will be included.

This way, existing API calls would be unaffected, and in future a clearer separation is made between detecting which versions are supported and the capabilities of that particular version.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/2162#issuecomment-470444213
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20190307/7a2a155c/attachment.html>