On Friday we discussed how to construct an API request, today we will discuss how to handle the response that the server returns.

Server replies

The elggVoices server will respond with a result packet containing a number of fields. The format of this reply depends on the format requested. From the manual:

• ‘status’: The status code, 0 for success or a non-zero error code.
• ‘message’: If the status code is non-zero this contains a human readable
  explanation.
• ‘result’: The mixed result of the execution, this may be a simple type
  (int, string etc), an array or even an object, depending on the API being
  called (see also result objects).
• ‘runtime_errors’: If there have been any runtime errors picked up by
  the internal error handler during the execution of the command, these
  are given here in an array.

The server result will be returned, serialised in the requested format (xml,php or json).

Errors will often give details pointing to what went wrong, these can be helpful when debugging your application or when looking for support on the forums.

Have a look at this XML formatted error message, XML success messages will be of a similar format:

<SearunnerResult>
<status type="integer">-1</status>
<message type="string">Missing X-Searunner-apikey HTTP header</message>
<result type="string">exception 'APIException' with message 'Missing X-Searunner-apikey HTTP header' in /home/liveshouts/html/lib/api/validation.php:109
Stack trace:
#0 /home/liveshouts/html/api/endpoints/rest.php(19): get_and_validate_api_headers()
#1 {main}</result>
<runtime_errors type="array">
<array_item name="0" type="string" >DEBUG: 2008-02-24 18:38:19 (UTC): & quot;Undefined index: method& quot;
in file /home/liveshouts/html/lib/engine/input.php (line 30)</array_item>
<array_item name="1" type="string">DEBUG: 2008-02-24 18:38:19 (UTC): &quot;Undefined index: HTTP_X_SEARUNNER_APIKEY&quot; in file /home/liveshouts/html/lib/api/validation.php (line 107)</array_item>
</runtime_errors>
</SearunnerResult>

Thanks for visiting! If you found this helpful, you might be interested in knowing that I offer development and consultancy services, and am available to hire!

Related