I’m having a hard time interpreting the following Server Responsibilities:
Servers MUST respond with a 415 Unsupported Media Type status code if a request specifies the header Content-Type: application/vnd.api+json with any media type parameters.
Does the above mean that a 415 HTTP status response must be sent only when the content type is application/vnd.api+jsonand media type parameters are included? What if a client sends application/json or something else? What if the client doesn’t send the header?
Servers MUST respond with a 406 Not Acceptable status code if a request’s Accept header contains the JSON:API media type and all instances of that media type are modified with media type parameters.
And given the Accept header also needs to be checked (if present), does it mean a client can send one or the other, or both?
Currently, my interpretation is as follows:
A client can send Content-Type, Accept, both or no headers.
If any of those headers is passed and the value is exactly application/vnd.api+json or anything else (as long as it doesn’t have application/vnd.api+json with media type parameters), it’s fine.
Ok, I think I get it now. Both Content-Type and Accept headers cannot have Media Type parameters (the parts after the first ;). Ex: VALID application/vnd.api+json, INVALID application/vnd.api+json; foo=bar However, starting with JSON:API 1.1, there will be two allowed parameters, profile and ext (extensions).
One question remains though, is the q factor/weight parameter allowed? It’s common with the Accept header, but unlikely with XHR requests I suppose.
Regarding the Accept header. What media types are valid? Just application/vnd.api+json? For example, how should the server respond if application/xml is supplied?
Not really what you’re asking, but application/xml, like application/json, is a pretty useless media type, since it only identifies the syntactic layer of the response, and not the semantic layer. Find something more specific if possible.
That said, there’s no reason you can’t provide alternatives to application/vnd.api+json where they make sense. The Accept header from the client tells you what they’re willing to accept, and (if used properly) which media types are preferred. If there are XML (or any other) formats that make sense for your data, they’re fair game.
There are many articles around the 'net discussing the need for content negotiation for REST APIs. (Such as REST implies Content Negotiation.) Whether you actually need that depends entirely on your project and who’s building the clients.