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.
Sure, the 5xx error class exists for such cases, but in reality the affected middleware components often have no way to know that the error is on their side and then just assume that the error is on the client side, and then respond with a 404 instead of 500/503.
Therefore based on the status code alone the client cannot distinguish between a 404 that means “empty result set” and a 404 that means “something is seriously wrong, report this error to the ops team”.
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 and the 404 is actually coming from the tomcat that it’s supposed to be installed into, instead of from the application itself? These two scenarios yield the same status code, but they are fundamentally different in their meaning.
-> For applications that need to know that a requested resource positively does not exist instead of just being temporarily unaccessible, 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. It’s using an error mechanism to communicate a valid result.
Another perspective: From an operations point of view a 404 may be problematic. Since it can indicate a connectivity problem rather than a valid service response, i would not want a fluctuating number of “valid” 404s in my metrics/dashboards that might conceal genuine technical issues (e.g. a misconfigured proxy somewhere in the request routing) that should be investigated and fixed.
This is further excarbated by some APIs even using 404 instead of 401/403 (e.g. gitlab does such a thing), to conceal the information that the request URI would have been valid but the request lacked authorization to access it. In this case too a 404 should be treated as a technical error and not as a valid “resource not found” result.
Edit: Wow, this has caused a lot of controversy. Here is another argument against 404: Strictly from a HTTP spec (RFC7231) point of view, 404 does not even mean that a resource does not exist. It only means that the server has no current representation of the requested resource available, and this even may be only temporary. So strictly by HTTP spec, 404 is inherently unreliable regarding the nonexistence of a requested thing.
If you want to communicate that the requested thing positively does not exist, do not use 404.