Thursday, 15 January 2015

API development in Rails error path

In my series of of API development I haven't covered the error handling.

Let me share my experience with you about what I have learned about proper error handling.
I call error path the case when the user can't achieve what he wants.

This case can happen by the following reasons:

  • The user calls an invalid url
  • The user addresses a missing resource
  • The user misses a mandatory parameter
  • The uses passes a wrong parameter
  • Some other internal error occurs
  • ...

Since thousands of calls can be made daily or hourly against the API there is no way to stop the server and debug it. So all the information related to the erroneous call must be recorded. Basically all the information to reproduce the error must be recorded. I call this ApiCallAudit.

Such an ApiCallAudit must contain:

  • All the incoming parameters
  • The type of call (GET, POST, DELETE, ...)
  • cookies
  • backtrace
  • created_at
I added some additional fields to it for filtering purposes:

  • level. It serves to quickly determine the possible source of errors. It could be parameter_error, unexpected_error, parameter_missing_error, entity_missing_error
  • status. It is a default error message.
  • code. An error code which uniquely identifies the error.
In the beginning the error code was missing from my design and the mobile clients were using the default error message. This has some disadvantages:
  • The mobile UI is usually developed in a different codebase. And the server side error message modification is not possible. Specially if the same chunk of server side code is serving many applications.
  • -The language used on the mobile UI can vary. For example the UX developer can decide to use:
    1. "You haven't provided the group" - First person complaining style.
    2. "The group is missing" - Passive objective style
    3. "Please provide a group" - Proactive gentle style
    4. "Select a group!" - Imperative style
    5. ...
In order to formulate the sentences which reflects the application mood the mobile developer needs to interpret the returned error based on its error_code and formulate its own corresponding message.

Happy coding :)