3 ms·

> If the caller is going to get back a serialized status message (["Not found"]), then the HTTP request was successful, and it should return 200. Now all clien

by buro9 11y ago

> If the caller is going to get back a serialized status message (["Not found"]), then the HTTP request was successful, and it should return 200. Now all clients have to implement their own error checks, string parsing, just to discover something that the HTTP layer could have told you explicitly, that the resource requested could not be found. If an API treats data as resources, then the API should return HTTP status codes that clarifies how the query against the resource was handled. "Could I have this?" = "404 Not Found" is a great response. "Could I have this?" = "200 OK" (not really) is a crap response.

voltagex_ 11y ago
Yeah, I hate APIs that return 200 with a JSON (or XML) body that says the response was anything but OK. Another bugbear is a server suddenly switching content types for errors. If you're on IIS, make sure you're handling your own damn error pages so I don't suddenly have to account for an HTML 500 error page in my javascript code. Cisco's AXL API was a terrible offender for this one.
- bencollier49 11y ago
  Agree, the number of APIs I've dealt with which return 200 OK for everything and then drop errors into the body of the response is horrific. My favourite are the "200 OK" responses with a Java error trace in the body of the response.
- TheOtherHobbes 11y ago
  I've never used IIS, but isn't that confusing protocol codes with content codes? IMO HTTP status codes should return information about the HTTP transaction, and only about the HTTP transaction. If you run an API layer on top of that, that's a separate concern. So "Server busy" should not be in the same space as "That API request was bad." On my last project I returned 200 for successful transactions, 404 for missing pages, and 444/closed connection for 'Piss off and stop making inept attempts to hack this server, use it as a free proxy, or rack up your SEO stats." IPs trying any of the latter are blocked by Fail2Ban. 444 seems to have cut down on spam requests from botnets, and it's cheaper than serving a full 404 page.
ErrantX 11y ago
Well from a client library point of view: * Make request * Has error status code? * Error * Make request * Has error string message? * Error Fairly similar code-paths. If there was a very consistent implementation of REST API's and how they worked/responded this argument might have more legs; because client libraries could have a shared base libraries which handled this logic. As it is, API specific libraries have to implement error handling logic so it doesn't really matter.
- buro9 11y ago
  The problem there is that error strings tend to change over time... an error match today may fail tomorrow. Additionally too many clients think that error messages are safe to be shown to end users. In reality error messages are seldom to never fit to be shown to end users, not least because they're not localised, but also because the target audience for an error message for an API is the developer, not the end user.
  - bluetomcat 11y ago
    What's the problem with including an additional user-friendly, alert-friendly, localized message in the payload? That's a much better general solution than trying to figure out which nonsensical HTTP status code to return.
    - buro9 11y ago
      How does an API know the context surrounding a message to be presented? i.e. is the client a mobile one? Does it have limited space to display a message? Is the client actually a desktop client calling the API with specialist needs to show a system dialog with specific properties filled that is more than just a single error string? An API is an interface to interact with the web application, beyond providing the means to interact with resources it should make few to no assumptions about how clients of the API will act, their environment or constraints, their locale requirements, or anything. The client is best placed to decide how to communicate to the end user, and the best thing the API can do is provide clean and unequivocal instruction to the client that something has happened so that the client can do it's job of handling it how it feels is best.
bluetomcat 11y ago
This just complicates the handling of the request on the client for no apparent benefit. And there are many more HTTP codes besides 404 which are mostly meaningless (payment required, anyone?), or fit very poorly within the application logic. It is a layer of legacy cruft that is best avoided. Non-200 codes should indicate some exceptional situation on the server and could be handled client-side as "server configuration exception".

by buro9 11y ago

voltagex_ 11y ago

Yeah, I hate APIs that return 200 with a JSON (or XML) body that says the response was anything but OK. Another bugbear is a server suddenly switching content types for errors. If you're on IIS, make sure you're handling your own damn error pages so I don't suddenly have to account for an HTML 500 error page in my javascript code. Cisco's AXL API was a terrible offender for this one.

bencollier49 11y ago
Agree, the number of APIs I've dealt with which return 200 OK for everything and then drop errors into the body of the response is horrific. My favourite are the "200 OK" responses with a Java error trace in the body of the response.
TheOtherHobbes 11y ago
I've never used IIS, but isn't that confusing protocol codes with content codes? IMO HTTP status codes should return information about the HTTP transaction, and only about the HTTP transaction. If you run an API layer on top of that, that's a separate concern. So "Server busy" should not be in the same space as "That API request was bad." On my last project I returned 200 for successful transactions, 404 for missing pages, and 444/closed connection for 'Piss off and stop making inept attempts to hack this server, use it as a free proxy, or rack up your SEO stats." IPs trying any of the latter are blocked by Fail2Ban. 444 seems to have cut down on spam requests from botnets, and it's cheaper than serving a full 404 page.

ErrantX 11y ago

Well from a client library point of view: * Make request * Has error status code? * Error * Make request * Has error string message? * Error Fairly similar code-paths. If there was a very consistent implementation of REST API's and how they worked/responded this argument might have more legs; because client libraries could have a shared base libraries which handled this logic. As it is, API specific libraries have to implement error handling logic so it doesn't really matter.

buro9 11y ago
The problem there is that error strings tend to change over time... an error match today may fail tomorrow. Additionally too many clients think that error messages are safe to be shown to end users. In reality error messages are seldom to never fit to be shown to end users, not least because they're not localised, but also because the target audience for an error message for an API is the developer, not the end user.
- bluetomcat 11y ago
  What's the problem with including an additional user-friendly, alert-friendly, localized message in the payload? That's a much better general solution than trying to figure out which nonsensical HTTP status code to return.
  - buro9 11y ago
    How does an API know the context surrounding a message to be presented? i.e. is the client a mobile one? Does it have limited space to display a message? Is the client actually a desktop client calling the API with specialist needs to show a system dialog with specific properties filled that is more than just a single error string? An API is an interface to interact with the web application, beyond providing the means to interact with resources it should make few to no assumptions about how clients of the API will act, their environment or constraints, their locale requirements, or anything. The client is best placed to decide how to communicate to the end user, and the best thing the API can do is provide clean and unequivocal instruction to the client that something has happened so that the client can do it's job of handling it how it feels is best.

bluetomcat 11y ago

This just complicates the handling of the request on the client for no apparent benefit. And there are many more HTTP codes besides 404 which are mostly meaningless (payment required, anyone?), or fit very poorly within the application logic. It is a layer of legacy cruft that is best avoided. Non-200 codes should indicate some exceptional situation on the server and could be handled client-side as "server configuration exception".