Errors handling in web services

Exceptions

Format

Exceptions are caught by the server that generate its own error format. All exceptions contain a translated message + debuginfo.

REST-XML

<?xml version="1.0" encoding="UTF-8"?> <EXCEPTION class="invalid_parameter_exception">

   <MESSAGE>Invalid parameter value detected</MESSAGE>
   <DEBUGINFO></DEBUGINFO>

</EXCEPTION>

How to handle exception on the client side

• Message: not translated error message (static => code error)
• Debuginfo: not translated detailled error message (dynamic => this message can change following the error)

As debuginfo is only available on development mode site, client developers can only display a not detailled error message to their client. They'll have to do their best to avoid to trigger exception.

When to send an exception on the server side

• DB WRITE functions must rollback when an exception is raised. We usually throw back the exception to the server.
• Example: the user does not have appropriate access rights to call the function)

Warning messages

Format

The warning format is different following the protocol. It can be JSON or XML. REST/SOAP/XMLRPC all got different XML format. However they all implement the following structure: list of (

   object {
       'key' string   //the key can be matched by the client developer
                       to find out what kind of error happened and implement a specific behavior against this error. 
                       For example: "userdoesntexist"
       'debug' string   //a not translated debug message to help the client developer to 
                          know straight away what is the issue
       'elementsdesc' string  Optional //explaination of the elements. For example:
                                        "elements is an array containing the missing user id" 
                                        "elements is a list of failing course id" or 
                                        "elements is an array(context, component, area, itemid) - the failing grade" or
                                        "elements is a list of non existing course/category 
                                        like (courseid1, categoryid1, courseid2, categoryid2...)"
       'elements'   //list of element
           list of ( 
               string/id/boolean/... (primary type)
           }
   }

}

How to handle warning on the client side

Parse the warnings. You should be able to implement some code logic against the returned warnings.

When to send a warning on the server side

Most of the time you send warning in get_xxx() functions.

• Example: the user is requesting information for a list of courses and one of those courses in no longer available