Content-type requirements has vague wording


#1

The wording in the “Content Negotiation” section of the documentation seems vague to me. I feel that I know what it means, but I want to clarify and if anyone agrees that it’s vague I may open a pull request.

Under “Client Responsibilities” it reads:

Clients MUST send all JSON API data in request documents with the header Content-Type: application/vnd.api+json without any media type parameters.

This could mean two distinct things. The first is that it could mean that all requests MUST have the Content-Type application/vnd.api+json and also MUST NOT have media type parameters. The other meaning is that any request THAT HAVE the Content-Type application/vnd.api+json MUST ALSO NOT HAVE media type parameters.

I assume it means the first, but it is very easy to intemperate the meaning as the second. There are a few places where unclear statements such as this are made.

Am I correct in the interpretation? Should it be rewritten to be more clear?


#2

I’m not seeing any difference with your distinction. JsonAPI requests must be application/vnd.api+json with no additional mediatype parameters e.g. version in “application/vnd.api+json;version=1.1”.

Your question is worded as an identity function, and I don’t see where the misunderstanding of any distinction between the two statements stems. All requests to the JsonAPI specification service are required to be in this format.