REST Development: Why HTTP Status Codes are Important

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.  

Most Common Codes to Use For HTTP Requests 

There are a few common codes that developers should start with. They 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 

HTTP Status Code Best Practices 

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. 

Looking for a Fast File Transfer Tool for Your Organization? 

FileCatalyst can help bolster your organization’s file transfer speeds and large file transfer capabilities. 

Start Free Trial