2XX - Request was understood and we found what you were looking for
can be broken down into two parts:
1. Request was understood
2. We found what you were looking for.
This guy seems to be advocating that completing a search and there being no results is actually a successful request, and so should be responded to with 200.
The problem though is that the spec (RFC7231) requires a representation of the resource to be sent in response to a GET.
If there's no payload, then you can send a 204 instead, but this raises its own challenges - a 204 just means that the server is not sending content, not that no content was found (which is a subset of 'not sending content').
I think on balance, 404 is correct - the spec indicates that it should be used where there's no current representation, which I think is an accurate description of a failed search.
Adding to this, it is far easier for clients to parse response codes than bodies. TFA makes the following claim:
> Returning a 2xx code immediately tells the client that the HTTP response contains a payload that they can parse to determine the outcome of the business/domain request.
Which is wrong. Response codes say nothing about the body.
Parsing the response body requires much more work: determining the format of the response received by the client, parsing it, validating it, handling edge cases, and so forth.
Further, it is possible, however unlikely, that the client does not accept application/json. Now what? Now there is yet another problem you have to solve.
And don’t forget the server has to generate all this as well.
All of this could have been avoided simply by returning a simple 404.
Actually, that's not correct. A response code can say a fair bit about the body, especially about whether it exists or not, but in some cases also the nature of the body. For example, a 203 says that the body of this request is not the same as the body sent by the origin server. A 204 tells the user agent that there's no body. 400s and 500s SHOULD have a body which includes an explanation of the error.
I agree about 4xx bodies, generally. They indicate that the request was malformed or unsuccessful in some way. The requester can fix this problem.
I think a 5xx should always represent an error on the server side that the requester cannot fix. It is always a bug or system failure to return a 5xx, which should be fixed by the API operator. Therefore no details are required or desirable to return to the requester.
6.6
[...] Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation[...].
Unless the user can fix the problem, and you want them to try, an explanation of a 5xx error adds no value. Again, I don't think 5xx is ever a valid response from an API -- it's always a server-side error (code or infrastructure) that needs fixing, often with high priority.
In many environments (e.g. medical, financial, or other secure/private), providing details on server errors is strongly discouraged. Even when the data isn't sensitive, I think you're asking for trouble by broadcasting server-side problem details to users.
I think my original point stands though, that status codes do tell you about the body in some circumstances. Or SHOULD tell you something about the body at least :)
So yes, it is correct to say that response codes say nothing about the body.
In general, applications using REST should follow these semantics.
2XX - Request was understood and we found what you were looking for
4XX - Something was wrong with the request on the client side. The client should take some action before retrying.
5XX - Something was wrong with the server and you can retry this request sometime later and it may work.