3 ms·

One point that didn't get addressed in this article is the use of HTTP status codes to indicate the result of a request. REST encourages proper use of status co

One point that didn't get addressed in this article is the use of HTTP status codes to indicate the result of a request. REST encourages proper use of status codes – 404 for a missing resource, 422 for invalid data, 201 for successful resource creation, etc. – further enhancing the predictability of the API. How does RPC handle status codes?

seanp2k2 11y ago
And yet still so many API developers don't get this, or don't know about it, or don't think it's important. Generic API errors are also pretty bad; a ton I've used will just throw a 400 (or 500) with no information on why. Relevant: http://blogs.mulesoft.org/api-best-practices-response-handling/ http://blogs.mulesoft.org/api-best-practices-response-handli...
MichaelGG 11y ago
Eh, sorta. Send an invalid body, say an unavailable product ID, or an invalid quantity. What error will you return? HTTP codes and REST might make sense for some simple scenarios (like managing files), but it breaks down fast otherwise. Shoehorning everything into the few codes HTTP has seems pointless.
- mryan 11y ago
  > Send an invalid body, say an unavailable product ID, or an invalid quantity. What error will you return? In this case the client has sent an invalid request so the response should be 400 Bad Request or 422 Invalid Data, with details of the error in the response body.
- lloeki 11y ago
  400, 422 (or even 404 if the product id was part of the resource URL). That's not shoehorning, that's using something which defines a crude yet semantically consistent granularity, that does not prevent having more detailed errors in the response body and/or additional headers. So I get a level of abstraction for free, increasing consistency in semantics and behaviour both inside my API and outside, easing debugging and allowing me to use off-the-shelf HTTP components (including curl) while leveraging common knowledge of the protocol across applications. The pet peeve issue I have with RPC/HTTP APIs is that people keep reinventing HTTP on top of it, only badly (at which point they may as well use RPC/TCP). That's why I like REST/HTTP, because I can "reuse things" when the problem model fits well within that tool (and it very often does). If REST/HTTP becomes a constraint instead of an asset, then maybe one should not use either REST or HTTP, and I'm fine with it because that was not the tool for the job. This is a tool, not a religion.
- Corrado 11y ago
  Not using HTTP codes is much, much worse. I've dealt with SOAP/RPC APIs that return nothing but 200, no matter what. The actual status is an english word in the response body (i.e. OK, ERROR, etc.) That is a nightmare to deal with because you have to manually decode each and every request instead of using a library to do the heavy lifting for you. Sometimes I have questions on which HTTP status code to use, but most of the time its pretty clear. And if you stick to the official codes most client side libraries will just work without any drama at all. As a bonus, all of the intermediate processes (proxies, firewalls, CDNs, etc.) will work as well without any finagling on your part. :)

seanp2k2 11y ago

And yet still so many API developers don't get this, or don't know about it, or don't think it's important. Generic API errors are also pretty bad; a ton I've used will just throw a 400 (or 500) with no information on why. Relevant: http://blogs.mulesoft.org/api-best-practices-response-handling/ http://blogs.mulesoft.org/api-best-practices-response-handli...

MichaelGG 11y ago

Eh, sorta. Send an invalid body, say an unavailable product ID, or an invalid quantity. What error will you return? HTTP codes and REST might make sense for some simple scenarios (like managing files), but it breaks down fast otherwise. Shoehorning everything into the few codes HTTP has seems pointless.

mryan 11y ago
> Send an invalid body, say an unavailable product ID, or an invalid quantity. What error will you return? In this case the client has sent an invalid request so the response should be 400 Bad Request or 422 Invalid Data, with details of the error in the response body.
lloeki 11y ago
400, 422 (or even 404 if the product id was part of the resource URL). That's not shoehorning, that's using something which defines a crude yet semantically consistent granularity, that does not prevent having more detailed errors in the response body and/or additional headers. So I get a level of abstraction for free, increasing consistency in semantics and behaviour both inside my API and outside, easing debugging and allowing me to use off-the-shelf HTTP components (including curl) while leveraging common knowledge of the protocol across applications. The pet peeve issue I have with RPC/HTTP APIs is that people keep reinventing HTTP on top of it, only badly (at which point they may as well use RPC/TCP). That's why I like REST/HTTP, because I can "reuse things" when the problem model fits well within that tool (and it very often does). If REST/HTTP becomes a constraint instead of an asset, then maybe one should not use either REST or HTTP, and I'm fine with it because that was not the tool for the job. This is a tool, not a religion.
Corrado 11y ago
Not using HTTP codes is much, much worse. I've dealt with SOAP/RPC APIs that return nothing but 200, no matter what. The actual status is an english word in the response body (i.e. OK, ERROR, etc.) That is a nightmare to deal with because you have to manually decode each and every request instead of using a library to do the heavy lifting for you. Sometimes I have questions on which HTTP status code to use, but most of the time its pretty clear. And if you stick to the official codes most client side libraries will just work without any drama at all. As a bonus, all of the intermediate processes (proxies, firewalls, CDNs, etc.) will work as well without any finagling on your part. :)