4 ms·

I don't want to be too hard on author here but this article is really misguided. Status codes are a very useful tool for observability and error handling and a

I don't want to be too hard on author here but this article is really misguided. Status codes are a very useful tool for observability and error handling and abusing HTTP 200 is a quick path to making your life difficult. Response bodies should disambiguate some of the different cases for the error (this path is wrong vs this employee doesn't exist) 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.

revscat 4y ago
> Status codes are a very useful tool for observability and error handling 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.
- d1sxeyes 4y ago
  > Which is wrong. Response codes say nothing about the body. 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.
  - quesera 4y ago
    > 400s and 500s SHOULD have a body 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.
    - d1sxeyes 4y ago
      That may be your opinion, but the spec is clear: 6.6 [...] Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation[...].
      - dragonwriter 4y ago
        SHOULD is not MUST [0], and “The user can do nothing about the problem and is likely to experience negative utility from any attempt to provide more detail than what the status code provides” is arguably a valid reason not to send a body with 5xx status responses. [0] https://www.rfc-editor.org/rfc/rfc2119.html https://www.rfc-editor.org/rfc/rfc2119.html
        d1sxeyes 4y ago
        Per my response to OP, I've been convinced on this.
      - quesera 4y ago
        "SHOULD" has a very specific meaning in RFCs. Contrast to "MUST". 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.
d1sxeyes 4y ago
I think the interesting part is that: 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.
- m3galinux 4y ago
  Completing a "search" SHOULD return a 200 with an empty results set. But a search is "/api/employees?name=Bob", not /api/employees/1199. The former is an endpoint that exists but was unable to find data: it should return the correct data structure normally returned for searches, but with no results. The latter is a direct link to a particular resource, which should 404 if it doesn't exist (as if any other file at a particular path doesn't exist).

revscat 4y ago

> Status codes are a very useful tool for observability and error handling 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.

d1sxeyes 4y ago
> Which is wrong. Response codes say nothing about the body. 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.
- quesera 4y ago
  > 400s and 500s SHOULD have a body 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.
  - d1sxeyes 4y ago
    That may be your opinion, but the spec is clear: 6.6 [...] Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation[...].
    - dragonwriter 4y ago
      SHOULD is not MUST [0], and “The user can do nothing about the problem and is likely to experience negative utility from any attempt to provide more detail than what the status code provides” is arguably a valid reason not to send a body with 5xx status responses. [0] https://www.rfc-editor.org/rfc/rfc2119.html https://www.rfc-editor.org/rfc/rfc2119.html
      - d1sxeyes 4y ago
        Per my response to OP, I've been convinced on this.
    - quesera 4y ago
      "SHOULD" has a very specific meaning in RFCs. Contrast to "MUST". 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.

d1sxeyes 4y ago

I think the interesting part is that: 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.

m3galinux 4y ago
Completing a "search" SHOULD return a 200 with an empty results set. But a search is "/api/employees?name=Bob", not /api/employees/1199. The former is an endpoint that exists but was unable to find data: it should return the correct data structure normally returned for searches, but with no results. The latter is a direct link to a particular resource, which should 404 if it doesn't exist (as if any other file at a particular path doesn't exist).