Multiple Output Formats For Web APIs

Yahoo! Developer Network has been pushing an interesting trend, providing REST API output in various formats. In addition to the more traditional XML output, you can also get serialized PHP and JSON (JavaScript Object Notation) output for many of their services. This includes other Yahoo! properties like the Flickr API (serialized PHP and JSON) and Del.icio.us API (JSON).

It isn’t hard to imagine why Yahoo! and friends would be interested in these format. Providing serialized PHP provides for easy consumption in PHP via unserialize. No matter how you feel about PHP as a language, it is insanely popular, so it makes sense to make it easy to use Yahoo! output in that environment. JSON appeals to both the JavaScript specific crowd and the more general XML crowd at the same time. With the resurgence of JavaScript in the last year or two JSON has specific appeal in the same way that serialized PHP does. But the simplicity and cross platform nature of JSON makes it a potential XML replacement.

Curious about how much work was involved in supporting these three formats (XML, JSON and serialized PHP), I put together a simple PHP class that can convert a PHP array to and from these formats. By using existing off the shelf PHP modules, Services_JSON from PEAR (or the json pecl extension if you have it installed) and PHP XML library by Keith Devens (with some minor fixes to quite warnings with PHP5) it turned out to be quite easy. You can grab a copy of the OutputFormat class, an example script on how to use it, Services_JSON and PHP XML library at http://josephscott.org/code/php/outputformat/outputformat.tgz.

Before you try it out there is one specific piece of information that you need to know about. The PHP array that is being converted must contain at least one layer. This requirement comes from supporting the XML format, which must have one root element to be valid. Here is an example of simple array that works, with a “person” layer (or root element):

$output_array = array(
  "person" => array(
    "name" => "Joseph Scott",
    "age" => 33,
    "url" => "http://joseph.randomnetworks.com/"
  )
);

Here is an example of an array that WILL NOT WORK (same example as above minus the “person” layer/root element):

$output_array = array(
  "name" => "Joseph Scott",
  "age" => 33,
  "url" => "http://joseph.randomnetworks.com/"
);

If you aren’t interested in supporting the XML format then both of the examples above will work just fine for JSON and serialized PHP.

Depending on the type of data that you have there is no reason to limit your self to these three formats. If your data fits into a feed model then the OutputFormat class could be extended to include RSS and ATOM. All the heavy lifting could be done using the FeedCreator class and Magpie or SimplePie to parse feeds back into PHP data structures.

I’m under no illusion that either of the non-XML formats with displace XML over night, but I do like having alternatives. And if you just want to get a quick idea what these three different formats look try out Yahoo!’s getTime service (using their YahooDemo appid):

• Traditional XML: http://developer.yahooapis.com/TimeService/V1/getTime?appid=YahooDemo
• Serialized PHP: http://developer.yahooapis.com/TimeService/V1/getTime?appid=YahooDemo&output=php
• JSON: http://developer.yahooapis.com/TimeService/V1/getTime?appid=YahooDemo&output=json
• JSON with function callback (JavaScript specific): http://developer.yahooapis.com/TimeService/V1/getTime?appid=YahooDemo&output=php&callback=my_func

So branch out a little bit. You don’t have to feel like XML is the only way to go.