API responses don't include version information

[jackdos]

As a consumer of the API, I want to know what version of the API/Schema the endpoint is implementing, so that I know how to marshall the response and what further queries, filters, etc are possible.

[jackdos]

Options:

1. Put the version in the http response header
2. Put the version in the http response body
3. Have a separate endpoint for querying version

Could we/would we want to support version negotiation?

[carlwilson]

This one's important for 1.3 IMO, I'd vote for the HTTP header implementation, it's simple and in every response automagically. A "cheap" HEAD request will get you the info you want then.

[carlwilson]

Letting people know the API version they are using is the first aim here. For that, I would suggest a custom HTTP response header that advertises the default version supported, e.g. PAR-Default-Version: 1.3 in the header. A quick HTTP HEAD request could then establish the version. There would be no way of knowing the version used for a URL as that information is in the header. ALL PAR response messages should contain a version attribute somewhere so that it's clear when looking at responses.

This would NOT be enough to support version negotiation. Support that through HTTP headers feels potentially clunky, but the following might work.

• advertise the available versions in a second HTTP response header list, e.g. PAR-Available-Versions: 1.3; 1.2; 1.1`;
• support negotiation via an HTTP request header, e.g. PAR-Version: 1.2; and
• add a custom HTTP response in case the requested version is unavailable.

This would still leave some implementation details for endpoints to support different versions, as the incoming request header would have to be checked, and the appropriate routing would have to be done behind the scenes.

[carlwilson]

API HEADER definition: Closed by #75

See openpreserve/par-wikidp#1