REST – Why HTTP Status Codes Are Important

by , May 1, 2013

There are many ways in which REST developers can tackle error handling. Most REST services will send some kind of error condition structure which embeds an error message describing the error and some kind of code. This is a good start.

However, for some REST services the HTTP status code is not well defined. In some cases the REST services send an OK status code of 200 regardless of whether an error was encountered or not. The problem here is that client developers have no sure way of detecting if a request was successful or if it failed. The only way the client application can detect the appropriate status is by interpreting the actual payload that was returned. This adds an unwanted dependency to client application development.

A further problem of simply returning a “200 – OK” status for all requests is that for certain requests one will not be sending any content. This can be an update, status check, or perhaps a deletion which requires no content sent back to the client application. In these cases a more suitable “204 – No Content” status should be sent.

In the case of an addition operation, such as adding a new contact in a phone list, it would be best to send a “201 – Created” status. Hence, a better approach is to set the HTTP status code as the HTTP specification describes. For instance:

The most common codes to use for any HTTP request are:
200 – OK
404 – Not found
500 – Internal Server Error

One can then expand to a more detailed set of statuses if required, such as:
201 – Created
204 – No Content
304 – Modified
400 – Bad Request
401 – Unauthorized
403 – Forbidden
501 – Not Implemented

One can see the entire list available at HTTP Status Codes

As a best practice at FileCatalyst, we do set the HTTP status code based on the request result. For example, if a request has no content the appropriate “204 – No Content” HTTP status is sent. Or if a new record is being created the appropriate “201- Created” HTTP status is sent.

We have also standardized our error structure to reflect the same structure as a FAULT SOAP service document. This was done deliberately to give SOAP developers a sense of familiarity with error handling using our REST services. Hence whenever an error condition is encountered by any of our REST services we will return the following structure:

{
     "fault": {
       "code": {
         "value": "Sender",
         "subcode": {
            "value": "InternalError"
         }
        },
       "reason": {
       " text": "Internal Error Detected."
        }
      }
   }

The above structure makes it easy for our client developers to use our REST services, knowing that all error conditions will be represented the same way. But more importantly with all errors returned to client requests, the appropriate HTTP status code is set. For instance, the above error would return an HTTP status code of “500 – Internal Server Error”.

Conclusion

Remember, the request payload is not the only important aspect of a REST service. What is also important is that when returning a client request, one must also set the HTTP status to the appropriate code which reflects the current request condition encountered. Sending “200 - OK” on every request regardless of the request content type is not acceptable.

No Comments Yet

Be the first to respond!

Sorry, comments for this entry are closed at this time.