API

API PHP Code Sample: XML Parsing

1. •  
     CommentAuthorcameron
   • CommentTimeOct 14th 2011 edited @ 10/14/2011 1:15 pm

    
   Up to this point, most of the code examples have shown how to make and form requests, but we really haven't shown you what to do with the result once you get it back from the API. Depending on what you set as your Accept header, you're either going to get XML or JSON back from the API. This forum post is going to concentrate on how to parse XML. The examples contained within are going to be in PHP, but there's such widespread support for XML in every programming language that most of the examples will be transferable to your programming language of choice with a bit of work.
   
   Note: XML parsing can be a bit tricky if you've never done it before. If after reading this you're not sure whether XML parsing is right for you, be sure to check out our post on how to parse API output using JSON.
   
   PHP really gives you so many options on how to parse XML that it can at times be a bit daunting. There are no less than 15 libraries within PHP for dealing with XML manipulation. This post is going to focus on SimpleXML, which is probably the most versatile of the PHP XML libraries.
   
   SimpleXML
   
   SimpleXML is probably the easiest, fastest way to parse XML in PHP, and its inclusion of XPath means that's it's also robust enough to handle almost any parsing issue you throw at it. Here's a simple request to get information about my account:
   
   GET https://api.myintervals.com/me

   
   The response from the server looks something like this (some information has been removed and replaced with '****', but most has been left intact):
   
   <?xml version="1.0" encoding="UTF-8"?>
<intervals personid="9999" status="OK" code="200" listcount="1"><me><item><id>9999</id><localid>13</localid><clientid>****</clientid><title></title><firstname>Cameron</firstname><lastname>Brooks</lastname><primaryaccount>f</primaryaccount><notes></notes><allprojects>f</allprojects><private>t</private><username>****</username><groupid>2</groupid><group>Administrator</group><client>Pelago</client><numlogins>2070</numlogins><lastlogin>2011-10-12 11:46:44</lastlogin><clientlocalid>****</clientlocalid></item></me></intervals>

   
   Now, the first thing your application is probably going to do is check to see if the error code you got back is what you expected. For a simple GET request, your error code should be 200 if the request was successful (more information on error codes can be found here). To get the status code using SimpleXML, you can use something like this (where $return represents the content returned from the API request):
   
   $xml = new SimpleXMLElement($return, LIBXML_NOCDATA);
$code = (int)$xml->attributes()->code;

   
   For the above request, the value of $code would be 200. An even better way to check for an error would be to do the following:
   
   $xml = new SimpleXMLElement($return, LIBXML_NOCDATA);
$error = isset($xml->error);

   
   It's very important that your code be set up to handle and account for all errors properly. Even if your request is perfectly formed, there is still a chance that you may receive an error code when you make a request. For the moment though, let's assume that the request goes through and I get the XML result I posted above. To get my first name, all I would have to do is the following:
   
   $first_name = (string)$xml->me->item->firstname;

   
   SimpleXML will let you parse XML like public object attributes. Each XML node is an attribute of the parent node and each node is an object of type SimpleXMLElement. More examples of basic SimpleXML can be found here. Since each node is a SimpleXMLElement object, you can get its value as a string by explicitly casting the object to a string.
   
   Now let's say you want to do something a bit more complicated. Say you want to get the names of all the projects that belong to a particular client. It's possible to do that by walking through the XML like we did before, but it's easier to use XPath.
   
   $xml = new SimpleXMLElement($return, LIBXML_NOCDATA);
$projects = $xml->xpath('//project/item/name');

   
   The xpath function returns an array of SimpleXMLElement objects that you can parse. But if you just want the names, you can quickly cast them to strings by doing the following:
   
   $projects = array_map('strval', $projects);

   
   I hope that gives you guys enough to get going. If I left anything out, please let me know. If you would like to contribute an example in a language other than PHP, please don't hesitate to do so. And as always, if you have any questions on how to parse the the response from the API or questions about the API in general, please don't hesitate to use this forum to do so.