REST API - what to return when query for a GET does not find a result

user_1807163 0
Viewed 20

I'm calling a backend REST endpoint that takes in a query param and searches for a matching result /people?name=joe, and I'm wondering what status code and return data I should be returning when no object is found in the DB matching name=joe.

Things I've considered:

  • If I was directly hitting an endpoint /people/joe and it was not found, then I would definitely return 404.
  • If I was hitting an endpoint that returned a list of results for a query like if /people?name=joe was supposed to return ALL people named joe, then I would just return 200 with an empty list as the body. But in my case, I can only have one object for each name, so I'm not returning a list, so this doesn't apply here.

So this is a different case where I'm hitting an endpoint and passing in a query param to "search" for some data. And it is expected that in many cases, the data won't exist yet. This seems pretty similar to the first bullet point above, but I don't like returning a 404 here since this is not necessarily an error.

Should I return a 200 but with an empty object {} as the body, and then my frontend should check if body == {} then take that to mean no data found?

Or should I still return a 404 here? Again, this is not really an error in my case which is why I don't want to use a 404, but if that makes most sense, then I could.

api-design rest web-services
2 Answers

Easy parts first - status codes are metadata of the transfer-of-documents-over-a-network domain (Webber, 2011). In the context of a GET request (which asks for the current selected representation of a resource), a 200 response indicates that the response content is a representation of the resource (as opposed, for example, to being a representation of an error).

Furthermore, URI are opaque: general purpose HTTP components do not make assumptions about the semantics of resources based on the spelling of their identifiers. In other words, the "rules" are exactly the same for both

/people/joe
/people?joe
/people?name=joe
...

So at the HTTP level, the answers to your question are easy: if there's a current representation, then you reply to GET requests with a 200 status and copy the current representation into the response content.

The hard parts are deciding when there is a current representation, and what it looks like. REST and HTTP don't have anything to say about that, really. It's a resource design concern.

For example, this is interaction "follows all the rules":

GET /people?name=dave HTTP/1.1

HTTP/1.1 200 OK
Content-Location: /people?name=dave
Content-Type: text/plain

Dave's not here, man

HTTP is a general purpose mechanism for asking for documents/transmitting documents over a network, but it is agnostic about what documents look like and what keys we use to identify documents in the store.

If you are dealing with representations that describe zero or exactly one things, it can still be reasonable to use a list which is either empty or contains exactly one element (if you are familiar with Option/Optional/Maybe: same idea, we're presenting something with the semantics of an iterable collection)

HTTP/1.1 200 OK
Content-Location: /people?name=dave
Content-Type: application/json

[]

HTTP/1.1 200 OK
Content-Location: /people?name=bob
Content-Type: application/json

[{ 
  ... 
}]
user_547340

I agree that 200 and empty collection is better than 404 in your scenario. I don't like the idea of looking for {}, it is not explicit enough.

Possible ways of doing this:

200 ok
{
    items:[]
}

200 ok
{
    size:0//, 
    //items:undefined
}

200 ok
[]

206 Partial Content
Accept-Ranges: items
Content-Range: items 0-0/0
// []
user_6070330
Related