need way for servers to advertise what HAPI versions they support

[jbfaden]

At our weekly meeting we discussed how an old client might be handled by a new server. Surely there will be clients stuck at a particular version, so it might be nice for a version 3.0 server to be able to drop back to 2.1 to support old clients. We briefly discussed a few different mechanisms which would address this, such as having the about response link to old versions of the server, or having a request header declaring the HAPI server versions supported.

[berniegsfc]

If a client sends a request using the older query parameter names (id, time.min, ...) a 3.0 server should assume it doesn't support 3.0 responses. If a client uses the 3.0 query parameter names (dataset, start, ...) a 3.0 server can assume the client can handle a 3.0 response.

[jbfaden]

I agree for 2.1 to 3.0, this probably isn't a problem. I think it will be in the future though.

[berniegsfc]

Yes, it would be good to have a better approach for the future. But the parameter names may not be enough for 3.0 since 3.0 can represent additional datasets that 2.0 couldn't. So a 3.0 server might want to send a different response to a catalog request depending upon whether the client is 2 or 3.

[jbfaden]

Here is a HAPI 3.0 server, for reference: https://jfaden.net/HapiServerDemo/hapi/.

[berniegsfc]

https://jfaden.net/HapiServerDemo/hapi/capabilities says it is a 2.0 server.

[jbfaden]

Thanks for pointing that out. I looked at one of the info responses and assumed I'd done all of them.

[jvandegriff]

in capabilities, have a link to other servers at the sate site that support other HAPI versions

capabilities : {
  "version": "3.0",
  "otherVersions": [ { "2.0" : "http://example.com/servers/2.0/hapi/" } ]
}

[jvandegriff]

From now-closed duplicate ticket #124

Currently, there's no way for servers to indicate that they support multiple versions of HAPI.

The about endpoint (and all endpoints, actually) report the version, so client know which version they are dealing with.

But as more versions of HAPI are created, clients will want a way to find out if a server supports different versions. This would be useful if a client handles only 2.0, and a 3.0 server could report that it could still do 2.0 if asked.

What about adding an entry in the capabilities endpoint object that identifies other versions of the spec:

otherVersions: [
         { "version": "2.1",  "url": "http://server.org/data/v2.1/hapi" },
         { "version": "3.0",  "url": "http://server.org/data/v3.0/hapi" }
        ]

Having fixed tags here seems better than tags that are version numbers.

Would not need to indicate revision number (as in 2.1.5, versus 2.1, since the last .5 is just for bug fixes). But having 2.1 instead of just 2 seems useful since 2.5 could have more features (but still be backwrds compatible).

This above approach (using otherVersions in the capabilities) is possibly non-standard - Bob found this reference with 4 methods:

https://www.xmatters.com/blog/devops/blog-four-rest-api-versioning-strategies/

[jvandegriff]

In the xmatters reference above, having a different URI for different versions is one of their suggested ways of handling version changes to a REST API.

The xmatters folks claim that a con of this approach is that version changes affect a lot of code, but the way we are handling it, that is not the case, or at least we can make it not the case. Clients should always try to use the latest version of a HAPI server at its standard (i.e. no version) location.

http://server.org/data/hapi

If the server has a newer version than the client, the client should then look at other supported versions and try to use one that is compatible. Those will have version-specific URLs as in the post above:

http://server.org/data/v2.1/hapi

If you have a version 3.0 server, and that is your latest, I do not think it should be listed in the otherVersions. The latest version is just what is available at the version-less URL for that HAPI server.

[jvandegriff]

Note: Older servers might not have all datasets.

[jvandegriff]

Server implementers are likely to just move on, but clients would need to be able to still find a compatible server, and this would let them do that.

We are now planning to wait on this until we see a need for it.