Errors handling in web services

Exceptions

Format

Exceptions are caught by the server that generate its own error format. For example in REST:

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

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

</EXCEPTION>

All exceptions contain a translated message + debuginfo.

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

/**

 * 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(
	               'key' => new external_value(PARAM_ALPHA, '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' => new external_value(PARAM_TEXT, 'a not translated debug message to help the client developer to 
                                 know straight away what is the issue'),
                      'elementsdesc'   => new external_value(PARAM_TEXT, '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' => new external_multiple_structure( new external_value(PARAM_RAW, 'an element can be used 
                                by the client developer implements some automatic code fixing on the client side')),
	           ), 'warning'), 'list of warnings'
	   );
	 }

When to send a warning

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