Errors handling in web services
From MoodleDocs
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="invalid_parameter_exception">
<MESSAGE>Invalid parameter value detected</MESSAGE>
<DEBUGINFO></DEBUGINFO>
</EXCEPTION>
REST-JSON
SOAP
XML-RPC
How to handle exception on the client side
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
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:
list of (
object {
'key' string //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' string //a not translated debug message to help the client developer to
know straight away what is the issue
'elementsdesc' string Optional //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' //list of element
list of (
string/id/boolean/... (primary type)
}
}
}
How to handle warning on the client side
When to send a warning on the server side
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