With error responses, such as 4xx and 5xx, are error objects in the response optional?
From reading http://jsonapi.org/format/#errors it seems like they are, but I’d like to confirm.
Thanks!
So, JSON:API — Latest Specification (v1.1)
A document MUST contain at least one of the following top-level members:
- data: the document’s “primary data”
- errors: an array of error objects
- meta: a meta object that contains non-standard meta-information.
The members data and errors MUST NOT coexist in the same document.
You are correct that the spec does not say that you MUST have at least one error document inside of the top-level errors key.
Also, the spec does not state that you MUST respond with any document, so it is perfectly valid to respond with an HTTP error code and no body.
Also at JSON:API — Latest Specification (v1.1)
A JSON object MUST be at the root of every JSON API request and response containing data.
(Emphasis added.)
So (a possible reading is that) if there’s no data being returned, for example because there is an error, then there is no requirement to return a JSON object.
However, it also says (ibid)
This object defines a document’s “top level”.
A document MUST contain at least one of the following top-level members
‘This object defines a document’s “top level”.’ seems to imply that the concept of a document exists independently of any JSON. If a document can be said to have a top level, that means that there are two distinct concepts: a document, and it’s top level, and that a document with no top level is still called a document.
Thus, when the spec says
A document MUST contain at least one of the following top-level members
(emphasis added) this seems to be saying that all responses must contain a JSON object, as specified ibid in the subsequent lines.
In order for the document to avoid the implication of JSON necessity, it would (seemingly) have to be written
A document’s top level must contain…
Which would leave room to say that a document doesn’t need a top level.
To conclude, I don’t know if it’s %100 clear what “document” and “top level” mean, but it seems that JSON must be returned always.
Which leaves us with the first quote
… containing data.
It could be explained that an error is data, especially because (I hope) there’s some sort of description included.
This would perhaps exclude if (due to routing, validation, run time errors, etc ) the request never reaches an actual JSON API end point, and perhaps means to say that there isn’t a requirement to ensure that all server messages be accompanied with JSON.
Can there be errors in a Request? In the specification, it only mentions that one of the three top level should be present in the document. So does that mean errors can be present in the request too?
This is another question that deserves its own topic.