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(
	               'messageid' => new external_value(PARAM_INT, 'message id is a string that can be parsed by the client developer 
                                 to find out what kind of error is it. For example: 'userdoesntexist),                   
	               'debugmessage' => new external_value(PARAM_TEXT, 'a not translated debug message to help the client developer to 
                                 know straight away what is the issue'),
                      'elementsdescription'   => new external_value(PARAM_TEXT, 'explaination of the element. For example: 
                                "elements is a list of failing user id" or 
                                "elements is an array(courseid, contextid, userid)" or
                                "elements is a list of couple course/category like (courseid1, categoryid1, courseid2, categoryid2...)" '),
	               'elements' => new external_multiple_structure( new external_value(PARAM_RAW, 'an element - it could be useful 
                                to let the client developer implements some automatic code fixing on the client side')),
	           ), 'warning'), 'list of warnings'
	   );
	 }

When to send a warning

TODO