API Responses

The ToldYa API responds to all requests by outputting a simple XML document. The values for each of the nodes in the XML document are HTML entity encoded to ensure the XML is valid. To use or display a value, ensure you decode the entities first. Using PHP, for example you can do this using the html_entity_decode method.

All API responses include a <status> node whose value is either SUCCESS or ERROR. If there's an error processing the request a <message> node will be included which contains a description of the error.

For successful GET requests, the API returns one or more records. See the documentation for the selected method to see examples of the XML output.

For successful POST requests, the API adds, removes or updates the selected record(s) and returns and XML document with a <status> of SUCCESS and one or more optional elements.

Example POST response (success):

<?xml version="1.0"?>
<toldyaapiresponse>
<url>https://www.toldya.com/api/</url>
<status>SUCCESS</status>
<message>User 'freddo' successfully created.</message>
</toldyaapiresponse>

If any errors occur processing your request, the API will return XML with a <status> of ERROR and a <message> describing the error:

Example Error Response:

<?xml version="1.0"?>
<toldyaapiresponse>
<url>http://toldya.com/api/</url>
<status>ERROR</status>
<message>The user name 'robert' is already in use by another user.</message>
</toldyaapiresponse>

Parsing the response

The API always responds with a valid XML document. You can then parse the XML using your preferred server language or XML parsing tool to get the values you want. In the following example, we use PHP's built-in simplexml_load_string to parse the results of a request to create a new user.

/**
 * call the create_user method of the API
 * using cURL - the XML response is written
 * to a variable called $result:
 */
//request code here

$result = curl_exec($ch);
/**
 * Use PHP's built-in method to transform
 * the XML into an object
 */
$sxml = simplexml_load_string($response);
/**
 * check the <status> node of the response
 * to see if the request was successful.
 */
if($sxml->status == 'SUCCESS') {
	/**
	 * drill down to the new username
	 */
	echo $sxml->result->username;
} else {
	/**
	 * get the error message
	 */
	echo $sxml->message;
}

 


back to top