2

My question is around error handling with a RESTful API. Traditionally people have used error codes and messages in the response body. My question is can you formulate those errors into full fledged resources. For example you might want to get the error as an HTML page or get a list of possible errors in json format. It seems quite natural for an error to be a resource.

However it seems a bit dirty to return a "resource" as an error for another resource but if you think about it an error code and an error message in the request body is just that without the extra useful semantics of a resource.

Also to be clear this shouldn't be a subjective question. I want to know if doing this would violate RESTful design principles or any notable relevant RFC for HTTP communication.

Edit:

One issue is the need to differentiate between error types and error instances. It pretty useful to have error types as resources but capturing every possible error instance and reporting that back isn't as useful.

Edit2:

The core of the question is if an error resource (different resource than requested) should be put in the 4XX/5XX response body. The question about if 200 + error or 4XX/5XX should handle errors is answered over here:REST API error return good practices

Community
  • 1
  • 1
trcarden
  • 881
  • 1
  • 9
  • 17
  • Related post might be http://stackoverflow.com/questions/2001773/understanding-rest-verbs-error-codes-and-authentication?rq=1 – trcarden Jan 04 '14 at 20:25

1 Answers1

3

While you most certainly can represent an error as a resource, your major issue will be that clients are going to find it hard to understand the error as an error; they'll interpret a success return code as an overall success. That's Wrong! (We've had a problem with this in one of the web applications at work, which handled errors by sending back a 200 with a document that had one of its fields saying that there was an error. It was a complete pain in the neck to deal with. Once we switched to using real error codes, clients worked much better.)

To mitigate against this, return JSON descriptions with your errors (payloads for the 4** and 5** messages) that describe where the resource containing further information is; the errors are still errors, but now they're errors with rich hyperlinked information. That's RESTful and actually pretty nice! You probably also ought to have some way for clients to discover these error resources that they ought to know about via other mechanisms, e.g., a /previous-errors resource that lists the ones that they're authorised to see. After all, discoverability is a good REST principle too; the state should be the state of resources (as much as possible) and as little as possible should need to be stored in clients.

Donal Fellows
  • 133,037
  • 18
  • 149
  • 215
  • Clients will do what your API documentation tells them to do. If you tell them that '200' means 'you communicated with us, now see the response to see what happened', they had better do that. – bmargulies Jan 04 '14 at 22:22
  • @bmargulies You're claiming that client authors read (or believe) documentation? Bwahahahaha! Oh, you're serious? Let me laugh some more! (Seriously, it's just going out of your way to make a rod for your own back. REST works much better when you try to be as conventional as possible.) – Donal Fellows Jan 04 '14 at 22:28
  • I've never really understood how this all works outside of Roy's religion, but a comment thread here is not enough bandwidth to get anywhere. Aren't there typically 1000 other subtleties that require client authors to, well, read the doc? – bmargulies Jan 04 '14 at 22:33
  • Guys let's keep our cool for a second. :) The whole 200 + error vs 4XX/5XX has already been settled over here: http://stackoverflow.com/questions/942951/rest-api-error-return-good-practices?rq=1. My question is more aligned with the second half of the answer. – trcarden Jan 04 '14 at 22:53
  • @DonalFellows constructing a previous-errors resource could quickly become a rather expensive resource to maintain but you could certainly keep the error-type as a resource fairly easily. Also isn't a bit of a mind screw to issue a request to resource A and get resource B back in the error payload? something seems right and something seems wrong there. – trcarden Jan 04 '14 at 23:00
  • 1
    @trcarden You don't have to keep them forever (10 minutes might be enough), but getting an object back in a [45]** response is legal HTTP and reasonable REST (as that's very strongly based on the HTTP concepts). You also don't have to do it for every error; for those that precisely match the general idea (e.g., a true 404) there's no need to give a custom resource for more info (“Not Found” is “Not Found”). – Donal Fellows Jan 05 '14 at 18:57