API PHP Code Sample: JSON Parsing

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 handle a JSON parsing PHP response. The PHP code examples contained within are going to be in PHP, but there's emerging widespread support for JSON in most programming languages (and third-party libraries available for pretty much every programming language), so most of the examples should be transferable to your programming language of choice with a bit of work.

JSON

JSON support in PHP is extremely straightforward, with just one common library to handle conversion of JSON data to and from PHP arrays and objects. JSON is rapidly gaining in popularity because of its readability, portability and its ability to be used within web browsers without any additional libraries. If you're wary of XML, JSON is probably your best route. With XML, it's usually best to work with your data directly within the XML parser you are using; with JSON, you can immediately convert your data into a PHP object or array and work with it using familiar PHP data structures, functions, and control flow structures.

So to start out, 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):

{"personid":"9999","status":"OK","code":200,"me":[{"id":"9999","localid":"13","clientid":"****","title":"","firstname":"Cameron","lastname":"Brooks","primaryaccount":"f","notes":"","allprojects":"f","private":"t","username":"cameron","groupid":"2","group":"Administrator","client":"Pelago","numlogins":"2070","lastlogin":"2011-10-12 11:46:44","clientlocalid":"****"}],"listcount":1}


Now, the first thing your application ought 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 json_decode(), you can use something like this (where $return represents the content returned from the API request):

$json = json_decode($return, true);
$code = $json['code'];


For the above request, $code would be set to 200. The second argument in json_decode() tells the function to return the result as an associative array (rather than an object). I'm doing it this way because I assume more PHP programmers are familiar with working with associative arrays than objects. An even better way to check for an error would be to do the following:

$json = json_decode($return, true);
$error = isset($json['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 JSON result I posted above. To get my first name, all I would have to do is the following:

$first_name = $json['me'][0]['firstname'];


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 simply a matter of iterating over an associative array, which you should be quite familiar with:

$json = json_decode($return, true);
$project_names = array();
foreach ($json['project'] as $project) {
$project_names[] = $project['name'];
}


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.