I’m writing a JSON API client library in elixir and so I’m trying to better understand what cases I’ll need to handle.
The spec says:
A JSON object MUST be at the root of every JSON API request and response containing data
(emphasis mine) and goes on to explain what that top level document should look like.
Does that mean the server may omit the JSON object entirely in some cases and respond with an HTTP status code and no response body at all?
I see no reason why not. I wouldn’t expect
GET /resource to contain a json:api document, so it stands to reason a 204 response shouldn’t contain a document either.
The only thing I would caution is that ‘data’ definition is a bit nebulous, considering the whole metadata is data concept, you might run into an issue where headers imply data.
Considering you’re writing a client and not a server, I would stand by the axiom ‘be liberal in what you accept, and conservative in what you send’. I would code for the possibility of no jsonapi document, and validate the request contents based on the context. It’s easier to add an exception scenario in later, than to try to redesign the library for the capability to handle the lack of a document.
The SPEC also says:
204 No Content
If a POST request did include a Client-Generated ID and the requested resource has been created successfully, the server MUST return either a 201 Created status code and response document (as described above) or a 204 No Content status code with no response document.