Rest WebService error handling.

Question

Hi there,

I am using RestWebservice for few basic operations , like creating/searching. The request xml looks something like this

<customer> 
    <name/>
  .....
 </customer>

For a successful operation I return the same customer XML with extra fields populated in it(eg. systemId etc which we blank in the request) . with Response.Status=2000

For an unsuccessful operation i return something like this with different error codes . e.g Response.Status = 422(Unprocessable entity) Response.Status= 500(Internal Server Error) and few others..

<errors>
<error> An exception occurred while creating the customer</error>
<error> blah argument is not valid.</error>
</errors>

Now i am not sure , whether this is the correct way of sending the errors to the client. Maybe it should be present in the header of the response.

I will really appreciate any help. Thanks!

Answer 1

I'd wrap the XML in "Request" or "Response" wrappers.

E.g.,

<customerrequest>
  <customer>
    ..
  </customer>
</customerrequest>

and more importantly:

<customerresponse>
  <status>success | failure</status>
  <customer> <!-- If success -->
     ...
  </customer>
  <errors> <!-- If failure -->
     <!-- never underestimate the value of having a machine-friendly error code 
          for each possible error, or critical/non-critical errors -->
     <error code="0001">An error occurred</error>
  </errors>
</customerresponse>

This also means that as your service matures, you can add extra non-data fields as required within the request/response tags. Or a reference number. Or authentication details.

If you were using SOAP, you could use the existing error handling that SOAP has built-in, although I have personally found it rather restricted (not that I investigated too deeply).

Answer 2

The correct REST approach for errors is to use the HTTP status codes (as it sounds like you are doing). There is a bewildering array of them (as you can see here) and you might be surprised to see how many may fit most common situations.

As far as friendly error messages, you have 2 choices. First, you can provide a text description of the status code after the status code in the HTTP response (see the Wikipedia article on HTTP for more info). This text is determined by the server--not the HTTP specification--and gives you some flexibility in the specific message you send; most server-side frameworks give you a way to set this text programatically. However! It is a best practice not to abuse the status code description, because you can't guarantee that the user's web client will read it or not (in favor of reading only the status code and using the standard HTTP descriptions). I would only recommend using this approach if your status descriptions are simple and you control the server and the client (so you know what you are getting). In my experience, this approach works pretty well for the 5xx range of codes, but I wouldn't use it for much else.

Your second option is what you are already doing: to return an error status code and a description of the error as the body of the message. That is a best practice; if it is working for you, no need to change. It is probably helpful to think of this as "additional information the errors" rather than the error message itself (which would be the text after the status code in the HTTP response).