API to return PHP arrays, but which method is best?

PHP
1

I’ve seen webservice APIs which return data values in a range of options, usually json or xml.

Sometimes I’ve seen one of the options to be PHP arrays being returned.

I’m exposing some data via GET and am thinking of returning json, csv, php arrays.

Does anyone know what is the best (or most acceptable or accepted) way to create and return the php array option?

Does it look like this - a valid PHP file with open and close tags? <?php etc


<?php

$array[] = "this" ;
$array[] = "that" ;
$array[] = "the other" ;

?>

Or is it a text file containing an array:


$array[] = "this" ;
$array[] = "that" ;
$array[] = "the other" ;

OR is it a stream containing


return serialize($array);

I’ve never come across this issue before and could do with a pointer.

While we are at it, any other general advice on char encoding, headers, gotchas etc gladly welcomed.

2

Hi, JSONP I’ve almost got that nailed now, a lot simpler than I thought.


if( isset( $_GET['callback'])
 return $_GET['callback'] . '(' . json_encode( $array ) ,')';

// else  return json_encode( $array );

As far as XML goes the data will not suit RSS as it will not link on to anything, and anyway contains about 15 custom fields, kinda:


<collection>
<job>
<title>Pole Dancer</title>
<office>Aston</office>
<location>B12 5AJ</location>
.... and so on
</job>
<job>
<title>Christmas Elves</title>
<office>Edgbaston</office>
<location>B11 3SS</location>
... and so on
</job>
</collection>

By looking at the Flickr API docs (and having consumed their data too) they just seem to wrap xml with


<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
	[xml-payload-here]
</rsp>

and then they call it a REST response, so I guess that is something I should be doing.

It’s good to read their own specs too because they are explicit in describing how failure will be flagged for the API users e.g.

If an error occurs, the following is returned:


<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="fail">
	<err code="[error-code]" msg="[error-message]" />
</rsp>

So, walking the dogs, it dawns on me that if I think of each of the “options” is merely an algorithm and that I can build up a class structure to deal with error handling, logging, caching etc which I may be able to use many times in the future.

Part of my brain is telling me that “I-spy a Strategy pattern”, but the other half is telling me to get SimpleTest out and start from scratch.


$array = array(
0 => array(
'title' => 'Pole Dancer',
'office' => 'Aston',
'Location' => 'B12 5AJ',
),
1 => array(
'title' => 'Christmas Elves',
'office' => 'Edgbaston',
'Location' => 'B11 3SS',
),
);

Thats what I’m starting out with, and I guess I’ll end up with the likes of:


$a = new webserviceFromMultiArray( $array ) ;
$a->setLogger( $logger );
$a->setCacher( $cacher );
$a->setResponseFormatter( 'WS_xml' );
return $a->getOutput(); // which may be the err msg

But then the webserviceFromMultiArray seems tied to the ‘WS_xml’ … so if I then decide to create a webserviceFromArray … anyway, I’ll start from inside and work my way out.

YAML, right, will take a look at the spec.

3

Thanks for your comments, I’ll go with serialized php and json then.

4

As you’re thinking of distributing the data in different containers, have you seen YAML?

It’s very lightweight, XML can come with a lot of overhead on both sides.

Checkout Symfony’s YAML, standalone, component and its [URL=“http://github.com/fabpot/yaml/tree/master/lib/”]source.

Good luck!

Anthony.

5

Hi Rajug, yes point taken, after looking at vimeo and Flickr I’m looking at returning xml now as well.

Thanks

6

What flavour(s) of XML were you thinking of using? There are a wide variety of standardised formats (think RSS, Atom, etc.) available depending on whether they suit your content, or there’s the plain old make-up-your-own-structure too.

Personally, my usual two depend-on output formats (besides HTML (:slight_smile: are JSON(P) and XML, both being generally as basic and concise as possible and being similar in structure (on knowing the structure of the JSON format, you should be able to guess correctly the structure of the XML).

7

tsk - always the way isnt it?

I just remembered where I saw php response format option, Flickr API

Using php serialize and unserialize.

8

This is indeed much easier method. But I am not sure if serialize and unserialize works with all other programming languages as well.

9

XML is the only most accepted format to return from any kind of web services APIs. I assume that you are not going to develop your web service API with any of the well known ways like SOAP, XMLRPC, REST. If you use anyone of them, it will not be confusion what to return because they have their own ways to return information.

Since it seems that you are developing your own API, it is really depends on what are the target languages/platforms as a client. So I would go for JSON or XML.

10

I would recommend either json or serialization. Json is ideal for JavaScript and the serialized array would be easy to manipulate in PHP. Your other options are a little unconventional requiring advanced parsing or eval. In the end through json and xml are the most universal if your going to have many different applications consuming the service using contrasting languages. There is a reason my most rest and non-rest services use either xml or json. That is because those are the easiest to manipulate universally between languages and environments. You could also use a name value pair if the response has only a single dimension. Name value pair seems most only used in legacy systems though before the web service revolution.