Errors handling in web services: Difference between revisions
Line 26: | Line 26: | ||
== Warning messages == | == Warning messages == | ||
Warning messages are included in the return value of each external functions. | |||
===Format === | ===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: | 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: |
Revision as of 04:34, 8 May 2012
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>
How to handle exception on the client side
- Message: not translated error message (static => code error)
- Debuginfo: not translated detailled error message (dynamic => this message can change following the error)
As debuginfo is only available on development mode site, client developers can only display a not detailled error message to their client. Clients have to do their best to avoid to trigger exception.
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
Warning messages are included in the return value of each external functions.
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
Parse the warnings. You should be able to implement some code logic against the returned warnings.
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