Review API-Guidelines: consider using content negotiation to request version of response

[dshorthouse]

The JSON API guidelines say little onj topic but there has been considerable discussion elsewhere about best practices for versioning API responses. Some people advocate for versioning to be expressed as part of the URL path (& as suggested in the API-Guidelines here), other people advocate for coordinating this through content negotiation.

I advocate for versioning to be accomplished as part of content negotiation instead of it being baked in the URL. The reason is that endpoints & their routes remain clean. Documentation is easier to maintain. There is no confusion between the model and the resource. Other documents like JSON-LD via other accept headers can be produced without being encumbered by the URL structure that was established for other content/responses. And, deprecation of a version does not have to result in complete loss of paths with a possible need for hard-coded redirects in a route (or elsewhere).

So, requesting specific versions of a response would look like this:

Accept: application/vnd.api+json;version=1.2.1

And the latest version would be like:

Accept: application/vnd.api+json

[falkogloeckler]

A more general question would be whether we assume backwards compatibility after updating to a new version. If that is not necessarily the case than the content negotiation approach makes only sense on a proxy-level in order to redirect to an instance of the desired version.
On a module-level this would make sense at least for accepting or rejecting requests to avoid exceptions, misleading results or even integrity issues. But if there is no other alternative to "negotiate" I don't see a difference to not mentioning the version at all.

So, I'd recommend to have the content negotiation for versions on a proxy-level. This would allow to:

• check dependencies already during or directly after module updates without the hassle of addressing the correct version numbers in the URLs of depending or related modules;
• at the same time we could still keep version numbers in the endpoint URLs of modules in case two versions of a module are installed in parallel.
• Content negotiation would be only the triggered if I send requests to endpoints without version number in the URL path;

Using only content negotiation for addressong versions would require that I'd need to know the version number in my request header. If my request is buried somewhere in the code I'd assume that would more effort to update the dependencies, than updating the URL.
However, we would need the dependencies on versions in a manifest (or similar) file anyways in order to facilitate the orchestration of the components.