What is the proper REST response code for a valid request but an empty data?
For example you run a GET request for users/9 but there is no user with id #9.
Which is the best response code?
- 200 OK
- 202 Accepted
- 204 No Content
- 400 Bad Request
- 404 Not Found
Answer
I strongly oppose 404 in favour of 204 or 200 with empty data. Or at least one should use a response entity with the 404.
The request was received and properly processed - it did trigger application code on the server, thus one cannot really say that it was a client error and thus the whole class of client error codes (4xx) is not fitting.
More importantly, 404 can happen for a number of technical reasons. E.g. the application being temporarily deactivated or uninstalled on the server, proxy connection issues and whatnot. Therefore the client cannot distinguish between a 404 that means "empty result set" and a 404 that means "the service cannot be found, try again later".
This can be fatal: Imagine an accounting service in your company that lists all the employees that are due to an annual bonus. Unfortunately, the one time when it is called it returns a 404. Does that mean that no-one is due for a bonus, or that the application is currently down for a new deployment?
-> For applications that care about the quality of their data, 404 without response entity therefore is pretty much a no-go.
Also, many client frameworks respond to a 404 by throwing an exception with no further questions asked. This forces the client developer to catch that exception, to evaluate it, and then to decide based on that whether to log it as an error that is picked up by e.g. a monitoring component or whether to ignore it. That doesn't seem pretty to me either.
The advantage of 404 over 204 is that it can return a response entity that may contain some information about why the requested resource was not found. But if that really is relevant, then one may also consider using a 200 OK response and design the system in a way that allows for error responses in the payload data. Alternatively, one could use the payload of the 404 response to return structured information to the caller. If he receives e.g. a html page instead of XML or JSON that he can parse, then that is a good indicator that something technical went wrong instead of a "no result" reply that may be valid from the caller's point of view. Or one could use a HTTP response header for that.
Still i would prefer a 204 or 200 with empty response though. That way the status of the technical execution of the request is separated from the logical result of the request. 2xx means "technical execution ok, this is the result, deal with it".
I think in most cases it should be left to the client to decide whether an empty result is acceptable or not. By returning 404 without response entity despite of a correct technical execution the client may decide to consider cases to be errors that simply are no errors.
Another quick analogy: Returning 404 for "no result found" is like throwing a DatabaseConnectionException if a SQL query returned no results. It can get the job done, but there are lots of possible technical causes that throw the same exception which then would be mistaken for a valid result.