Errors handling in web services

Exceptions

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.

Issue

clients can not match the function error because message error could be translated

Solution

The goal being to let the developer write his own error message, we should not translate the message. Maybe only using coding exception. In this case a second issue araise. Sometimes the exception comes from a core function call. In this case the exception message is already translated. We can not do much for it I suppose.

Error messages

• 16 functions: only throw exceptions - Note: this is the way that web service function should be implemented. Bulk functions should rollback transaction if an error occurs.

• 2 functions: the web service function catches some exceptions and return a string error message for each faulty element (create notes / send messages)

• download/upload script return string error message (JSON) + error code. The token script returns just an error message.

Issue

web service functions are not consistent. Some never return error message (exception is thrown and all transaction are rollbacked), and some bypass DB failure returning an error message (mostly linked to an id).

Solution

I think the web service developer still should choose if he wants to return an error message or an exception. The developer should still follow the rule about DB WRITE functions that must rollback when an exception is raised. We usually throw back the exception to the server.

Error 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 to know straight away what is the issue'),
                      'element'   => new external_value(PARAM_TEXT, 'element'),
	               'elementid' => new external_value(PARAM_INT, 'element id'),
	           ), 'warning'), 'list of warnings'
	   );
	 }