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="moodle_exception">

   <MESSAGE>This is a not translated message</MESSAGE>
   <DEBUGINFO>This is a not translated message with more detailled info</DEBUGINFO>

</EXCEPTION>

How to handle exception on the client side

• class name: can be used as a very generic code error
• Message: not translated error message (static => can be used as code error). NOTE: core lib functions throw translated error messages. Client dev should not consider them as 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. Not to mention that core lib function throw translated error message, clients 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

Warning messages are included in the return value of each external functions.

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:

   /**
    * Creates a warnings external_multiple_structure
    * @return external_multiple_structure
    * @since  Moodle 2.3
    */
   private static function warnings() {
       return new external_multiple_structure(
           new external_single_structure( array(
                   'element'   => new external_value(PARAM_TEXT, 'element', VALUE_OPTIONAL),
                   'elementid' => new external_value(PARAM_INT, 'element id', VALUE_OPTIONAL),
                   'warningcode' => new external_value(PARAM_ALPHANUM, 'the warning code can be used by
                              the client app to implement specific behaviour (e.g. "missingcourse")'),                   
                   'message' => new external_value(PARAM_TEXT, 'untranslated english message to explain the warning')
               ), 'warning'), 'list of warnings'
       );
   }

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

If something is going to be skipped or not done (WRITE operation) then it's an exception. Warnings only inform (WRITE operation) about some decisions made by the functions. Warnings must never prevents the WRITE operation to happen. It's the same for a READ operation. The results will be always returned, with or without warnings. if something prevents the results to be returned then it's an exception, not a a warning.

Example

• the user lastname is trimmed
• the language for this user was not specified so $CFG->defaultlang has been used.