Jsonapi resource is not present: 404 or { "data": null }?

Question

If a client requests a resource that doesn't exist from my REST application, like

http://localhost:8080/app/foo/1

and no Foo resource exists for that id, should I return a 404 error code? or should I return 200 with a body of {"data": null } ?

Reading this thread from ember data makes me think I should return a 404.

But when I read this passage from the JSONAPI spec it makes me think I should return {"data " : null}:

Primary data MUST be either:

• a single resource object, a single resource identifier object, or null, for requests that target single resources
• an array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections

because this case seems to be targeting a single resource.

In the section Parsing Data it says:

A server MUST respond to a successful request to fetch an individual resource or resource collection with a 200 OK response.

What does "successful" mean? if the query doesn't find anything because there's not an entry there, the query ran and got an accurate result, is that success?

and below that in the same section is:

null is only an appropriate response when the requested URL is one that might correspond to a single resource, but doesn’t currently.

where I'm not clear on what that is supposed to mean.

So which is it and why?

(This isn't meant to be specifically about ember-data, I would like to clarify what I should do to be in compliance with the spec. I only mentioned ember-data because it seems like a working reference implementation for how jsonapi should work.)

Prodigious

Answer 1

I know that I'm late to the game, but my answer might be useful for any lost souls.

The 1.0 specification specifically mentions that:

[... ] A server MUST respond with 404 Not Found when processing a request to fetch a single resource that does not exist, except when the request warrants a 200 OK response with null as the primary data (as described above).

The quoted passage is available here, under "Fetching resources". Specifically, the last part of the quote regarding the usage of null touches on the topics of reachability.

Ultimately, all REST APIs are supposed to be hypermedia-driven. The keyword here is "exploration". The JSON:API allows exploring the whole graph of resources via links (see the appropriate section of the specification). When in doubt between responding with 404 Not Found or {"data": null}, ask yourself this: does your API expose any links to the resource in question?

• If yes, this means that the request is semantically valid even though the resource either doesn't exist or it holds no data, thus you should respond with {"data": null}. For example, relationships and related resources are usually available from the root resource's links, empty or not – it doesn't matter.

• If not, this means that your resource is simply non-existent and you should respond with 404 Not Found. An example of this might be /users/1234567890, where there is no user with {"id": 1234567890}. It will not appear when fetching the public listing at /users and, as such, you will never be able to reach that link by following hypermedia-driven browsing.

In conclusion, the specification is not absolutely clear on this, but the intention is quite clear IMHO. Remember that you're designing a REST API after all.

Yama

Answer 2

The section you link to talks about a 'document'. If there is no document, all that is said there does not apply to the response. Also:

A JSON object MUST be at the root of every JSON API request and response containing data.

Note the 'containing data' part of this.

Return 404 Not Found.

Tralee