Why RESTful error handling is important?

Error handling is an important and integral part of API development and exposing public API. In loklak we have the APIs which return JSON responses exposed as REST APIs. REST, or Representational State Transfer represents an architectural style for building distributed applications. Unlike SOAP, REST-based web services do not have a well-defined convention for returning error messages. In general, these are the ways on which the errors are recognized, or thrown.

The most common errors that occur are HTTP Error codes, In many cases the hosted web services can result in a 503 and other similar errors indicating server errors which mostly mean that the server has crashed at a particular point. The reply to these is generally indicated back to the user as a HTTP Error code which is plaintext and doesnot conform to the reply format that the user is expecting resulting in the client application using the API to also crash.

In Loklak, the error codes are captured and handled properly.

Other common errors that have been occurring within loklak is missing pages of the content being served. However, these errors are commonly known as 404 errors and are indicated and emphasized similar to a web surfer hitting a brick wall. Loklak can now return an Error Document – This is how the 404 page came up. Here’s the loklak’s 404 page. 

The main challenge while building REST APIs is handling error conditions in each and every single API endpoint that has been exposed as a service. The challenge however is whether the error messages should be human readable error messages or application specific error messages or machine readable error messages.

However, the correct error message should contain a right blend of all the three types of messages. It should ideally enable the user to identify the error and the location where the error has been happening, a good way to indicate this, is the file or the type of error that has been occurring. This is human readable and it becomes useful especially for client side applications to use the APIs correctly. A 404 error status can help from a developer perspective but never to a user. Giving a proper message with details specific to the error can always be an add on.

Added to the details which are human readable it’s also important to have the right debug information regarding where exactly the error has occurred, these are called application errors. In these cases it’s useful to mentor the error code and a small stack trace so that it becomes easier to debug and find traces of repeated errors occurring in the service platform.

In addition to the human readable and application related errors, it’s also important to have more information for automatic code analysis tools to identify the errors automatically and take the required actions. This is however really useful in cases where there are background tasks that are running throughout the service. A user has requested an API endpoint which requires a specific set of libraries which might have been removed or not built in the built process. The automatic tools can use these machine errors to trigger the right actions like rebuilding or fetching updates of libraries and so on so as to avoid these errors.

Loklak is currently able to handle the error codes, give a generic error message while using the api’s, handle server errors and 404 pages. But this system can be improvised by providing with a error specific messages which can be a future enhancement.

Why RESTful error handling is important?