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

• DB WRITE functions must rollback when an exception is raised. We usually throw back the exception to the server.

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, 'warning is a string that can be parsed by the client developer 
                                 to find out what kind of error is it. 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(courseid, contextid, userid) - the failing context" 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

TODO