As can be found in the thread over at Clarify the versioning strategy for APIs, this is a highly controversial discussed topic and went on for over a year with no clarity in sight.
Actually, the only confusing part of JSON:API for us was to see that there’s not even a suggestion about versioning, but instead a rather surprisingly “rich” thread about it, and yet no resolution. 
We went for the double accept header like
Accept: application/vnd.api+json;
Accept: application/vnd.api+json; version=1.0
By my experience that’s accepted as by the specs by any implementation of JSON:API so far. 
I would like to know if this topic is currently officially addressed internally for a future specification or at least recommendation.
While this thread is rather old, my read of this is that it’s out of scope for the spec itself, and the related RFCs regarding content-type negotiation allow you to specify an extension for version if you like. As newer versions of JSON:API have a backwards-compatibility promise, I don’t think this is necessarily something that the spec needs to address. IMO.
1 Like
I prefer the Accept header method but version 1.1 of the spec (intentionally or not) prohibits it.
Under 6.3 Server Responsibilites it says:
If all instances of that media type are modified with a media type parameter other than ext or profile , servers MUST respond with a 406 Not Acceptable status code.
In other words, including anything other than ext= or profile= in the content type is prohibited.
So while I fully agree it should not be part of the specification I don’t think the spec should prohibit versioning methods either but it does actually prevent versioning via content negotiation.
I’m trying to figure this out myself currently as well and I’m leaning towards an X-API-Version header because I don’t like there being more than one URI that identifies the same resource.