1. REST == HTTP GET
2. HTTP+POX == HTTP GET & POST
3. SOAP == HTTP POST, with interop issues

When I’m talking to people about web services, and I hear them use various terms, this is what I feel they’re talking about most of the time.

REST

REST almost always indicates HTTP GET with a query string. The results are probably XML, but lately they could also be JSON.

No other HTTP verbs are used (especially PUT and DELETE), and it’s highly likely that all requests are routed through the same URI.

For example:

http://api.example.org/rest?action=search&query=trachtenberg

HTTP+POX

Nobody uses this term. However, there are some web services that, while not “true REST,” use more than HTTP GET. I place them in this category.

These likely exist because the service allows you to submit a large quantity of data that is not human readable, so it does not make sense to place as part of a query string. Blobs of HTML and pictures come to mind.

For example, the eBay “XML API”. You can submit items over eBay web services. Since the item description is pure HTML, it exceeded the maximum query string length our web server would accept at the time.

Thus, the eBay XML API was invented: you HTTP POST an XML document, we return an XML document.

Again, like REST, there’s no concept of resources. Everything goes through the same URI. The action is indicated either as part of the query string or in POST body. (Or both, as in the eBay case.)

SOAP

SOAP is identical to HTTP+POX, except that you’re required to use XML Namespaces and XML Schema.

You are also going to have interop issues when trying to generate the SOAP envelope to send or parse the SOAP envelope that’s returned.

XML Namespaces and XML Schema are minor headaches, but people are willing to deal with them. People understand that, in theory, namespaces are good, even if XML Namespaces are a little funky.

XML Schema can be confusing. However, it does allow you to validate the response, which most people find to be somewhat useful. The fact that XML Schema may not be the best way to describe XML data is a different issue.

If SOAP merely had these two issues, people would work through it. The real problem with SOAP is that the specification is so confusing, people can’t build interoperable clients and servers. This drives people mad.

People know how to generate arbitrary XML (it’s just text after all) and send a HTTP POST request. They also know how to parse XML, particularly when they know ahead of time what they should expect. (That’s why PHP 5’s SimpleXML extension is a great web services client.)

What they cannot do is decipher a WSDL file to determine what crazy combination of XML the server is expecting (especially when the server is not following the standard). And, assuming they can get through that, they cannot figure out how to repeatedly hammer their SOAP client into producing the magical combination of XML necessary to placate the SOAP server.

That’s the difference between HTTP+POX and SOAP.

It’s not the complexity. Well, it’s not complexity in terms of needing to build up a large document. It’s complexity in terms of trying to understand the hundreds of pages of XML specifications to generate the request and not having good examples of working XML documents to crib off of.

As to whether the message name should go in the URI? Nobody cares.

For example, at this year’s ETech, I broke through with a killer presentation titled: “eBay Web Services: A Marketplace Platform for Fun and Profit.”

Knowing a good thing when he sees it, Patrick from Google tries to respond at this month’s ZendCon with: “Scrub (Ajax), Wash (SOAP) and REST: use Google Checkout and AdWords APIs with PHP for fun and profit.”

Mixed metaphors and the ugly imagery of Patrick in the shower aside, I am not put off in even a small way by his outright thievery. For I am already sixteen steps ahead.

I am proud to introduce, coming on October 31th, for the very first time, my latest and greatest talk: “eBay Web services: Great platform or greatest platform?”

Truly Lincolnish.

PS: You are only allowed to read this if you have a sense of humor. This is meant to be funny. I don’t think Patrick is going around stealing all my talk titles, or even just my good talk titles. Besides, I am stealing my most recent one from Stephen Cobert, so I can’t really claim ownership to that now can I?

SOAP is obviously the big one. I use the PHP 5 ext/soap extension, which is great, but there’s actually another PHP SOAP extension that might be even better. No, it’s not PEAR::SOAP or NuSOAP; it’s axis2.

If you haven’t heard of axis2, you’re not alone. That’s because it’s a pecl extension that’s still in beta, so there aren’t a lot of people using it yet. However, it’s a PHP version of the Apache Axis 2.0 SOAP stack.

Unlike ext/soap, which is recreating SOAP one feature at a time, Axis 2.0 already supports a good portion of the WS-* specifications. So all that needs to happen is for someone to write the hooks between PHP and Axis 2.0, which is far easier than actually writing the features themselves.

I met a number of people from WSO2, the company that’s writing Axis 2.0, and they’re quite excited about the extension. However, they did mention it’s still in beta, so I haven’t actually spent any time using it yet.

The other PHP XML extension I’ve been hearing a lot about is SDO. SDO is an attempt to provide a standard data interface regardless of the backend datasource. So, for example, you can interact with XML data in the exact same manner as information pulled from your database.

At OSCON and ApacheCon, I’ve run into a couple of people from IBM who have been doing the heavy lifting on this extension, and we’ve had a number of interesting chats with them about eBay Web services and SDO, but I hadn’t had any free time at work to install the extension.

Therefore, when I had a little free time today between the end of my session and lunch, I sat down and reproduced a short code example that I had wrote using ext/soap with SDO instead.

Here’s the key portion of the original code:

// Print Titles and Mileage
if (isset($response->SearchResultItemArray)) {
    foreach($response->SearchResultItemArray as $item) {
        printf("%s\n\t%d miles\n", $item, $item->ItemSpecific['Mileage']);
    }
}

This iterates through a search result for eBay Motors listings and prints out the title and the mileage for each individual item.

Normally the code would be far more complex, but through a series of ext/soap class mappings I wrote that implement the IteratorAggregate and ArrayAccess interfaces, along with the __toString() magic method, I’ve managed to abstract away a number of the complexities.

Best I can tell, SDO doesn’t give me quite the same level of control, but it does implement a number of these features for me out-of-the-box.

Here’s my rewrite using SDO:

foreach ($root->SearchResultItemArray->SearchResultItem as $item) {
    $title = $item->Item->Title;
    $mileage = $item->ItemSpecific["NameValueList[Name='Mileage']"]->Value[0];
    printf("%s\n\t%d miles\n", $title, $mileage);
}

It’s not quite as brief, but I do get this nice XPath-like filtering that lets me pull out the the value of the car’s Mileage in one line. Pretty handy.

I had to implement the ArrayAccess interface to get this to work under ext/soap, which included this method:

public function offsetGet($name) {
	if (! is_array($this->NameValueList)) {
		$this->NameValueList = array($this->NameValueList);
	}

	foreach ($this->NameValueList as $NameValueList) {
		if ($NameValueList->Name == $name) {
			return $NameValueList->Value;
		}
	}

	return null;
}

Not the hardest thing in the world to write, but this is just one of the custom class maps that will arise in our data schema, and SDO takes care of them all automatically.

Still, right now I think I prefer my ability the greater control I have over the interface with ext/soap. Our SOAP schema isn’t that pretty since there are lots of list, array, and hash wrappers. Through classmaps and interfaces I can turn these into native-looking PHP arrays and hashes.

I may be introducing a leaky abstraction, but I think this is better than exposing a NameValueListArrayType for people to wrangle with.

Like ext/soap, SDO requires you to define your data using an XML Schema. While we actually publish a stand alone XML Schema file, SDO will also happily parse a WSDL file, too, which is nice.

However, it will not directly consume a SOAP message because the WSDL doesn’t include any mention of the SOAP envelope wrapper. I needed to rip out the contents of the SOAP body into a separate XML document in order to get SDO to parse my data. Oddly, this corresponds perfectly with our “XML API,” so I could use that to retrieve properly formatted data that I can pass directly to SDO.

Where SDO really falls down for me is performance. Admittedly, eBay is a pathological case, but our WSDL file is 2.94 Megs in size. When I feed that to SDO, it takes 8.5 seconds to process the XML Schema data. Yikes!

I don’t mind a one-time start up hit, but it doesn’t appear that SDO can cache a parsed version of the schema. In contrast, ext/soap has both an on-disk and in-memory WSDL cache.

This means it takes SDO about 8.7 seconds to process the schema, load in data, and print out the information — and all with locally stored files.

In contrast, ext/soap takes as little as 0.55 seconds to pull in a cached version of the WSDL from the disk, go out over the network to query eBay via SOAP, wait for eBay’s SOAP server to run a database query on its end and send back a SOAP response, parse the SOAP envelope, and print out the exact same data. If I was using the in-memory cache, I think it’d be even faster, and I’m sure the big bottleneck here is talking to eBay.

Now, I’ve spent all of 60 minutes playing with SDO, so it’s quite possible that I’m missing some obvious configuration flag. If not, I hope IBM can do something to help speed up the performance, since while I could probably write a script to break apart our schema to create individual files that contain all the possible types on a per-call basis, I am hoping I don’t need to.

In the meantime, I’m going to continue exploring SDO to see what else I can do with it because I’ve sure I’ve only grazed its surface.

[Update: I cannot get the axis2 extension to compile, despite trying a number of different versions of Axis2c and both Linux and Mac OS X. I may try again tomorrow.]

• DC PHP
• ApacheCon
• Zend/PHP Conference

I think I submitted a slightly different abstract for each conference, but the main core of all the presentations is the same: a case study of Dude, Where’s My Used Car, my eBay Motors / Google Maps mashup.

In particular, I show how I’m using the PHP 5 SOAP extension alongside magical methods and other PHP 5 goodness to provide a simple interface into eBay Web services. If you’ve never played with either ext/soap, the new OOP features, or SPL, then my goal is to introduce you to all the cool things they enable — things you cannot do in PHP 4.

If I get a chance to rewrite the front end AJAX code using a nice library, such as Dojo or YUI, I’ll show how I bind the data between the client and the server. Right now, the that particular code is handrolled, and totally sucks, so I won’t be showing that off. :)

If you’re going to ApacheCon, I am looking to roadtrip to Lockhart, TX for a little bit of BBQ. Let me know if you’re interesting in coming along, of if you can suggest someplace else to go instead.

All three conferences have posted their schedules and all three look great! With one of the east coast, one in the middle of the US, and one on the west coast, there’s bound to be a show close to you. Sign up, come on by, and say hello!

As usual, I had a great time at the show. It was fun to see all my old friends and make new ones.

I’ve spent many months using ext/soap with eBay’s WSDL writing sample code and testing out various functions. Bit-by-bit I’ve picked up a number of tricks and discovered quite a few un- (or mis- or poorly) documented features. Thanks to this talk, I will finally have the excuse to put them all together in one place.

Here’s the official description:

PHP 5’s ext/soap extension is an excellent Web services client. However, while the easy things are easy, lack of documentation means the hard things can appear downright impossible. Starting with SOAPClient basics and building upwards, learn the hidden secrets necessary to conquer even the strangest WSDL.

The one bad part about this talk is that I won’t be giving “Abracadabra and hocus pocus: Magical methods and PHP 5″ or “Consuming Web Services Using PHP 5.” Of the two, the first would have been a blast to give, but I already have slides for the second, which is nice. (Well, I haven’t heard one way or another about those talks, but I’m assuming they were rejected. That’s fine, since I only have time to prepare one talk.)

See you in Portland!

OSCON is my favorite conference of the year. There’s nothing else that provides such a wide range of interesting speakers and topics. I love learning about PHP, but I find it even more fascinating to see what the Perl and Python and Ruby guys are hacking on, or pick up JavaScript and AJAX tips, or heckle the Java programmers. :)

The past two years, I’ve been on the OSCON PHP track conference committee, so it was my job to write friendly reminders in my blog. I’m not doing that this year, so you can count on this as a unbiased plug for the show.

There are lots of topic areas beyond PHP, such as Web applications and Security, so you don’t need to be a PHP guru to submit. You just need to be doing something that other people will find interesting that you can share in an interesting way. The key is that when a conference attendee reads the description of your talk in the program that they say: “Cool! That sounds neat. I think I’ll go hear this talk.”

Last year, I wrote a short post about getting your conference proposal accepted. That’s just my personal philosophy, but I think it holds mostly true for all good conferences. There’s always the “I want the biggest names I can get” philosophy, but if that’s the case, then there’s nothing you can do about that anyway.

Proposals are due Monday, so hurry up and submit.

It’s the first year for NYPHPCon, but Hans and the whole NYPHP crew are great guys, so I know they’ll put on a teriffic show. When I still lived in NYC, I attended NYPHP user group meetings on a semi-regular basis, and they were even kind enough to let me present once or twice.

In fact, I gave my very first Web services presentation to NYPHP back in February of 2003. I don’t know if eBay would have hired me as a Web service evangelist if I hadn’t started down the path of learning about Web services for NYPHP. So, I owe them a big debt of thanks.

Besides, New York City is the best city in the world. Sorry Bay Area neighbors. Although, I certainly don’t miss the 22.8 26.9 inches, or .58 .68 meters for my non-US readers, of snow that got dumped on the city last night. Have I mentioned it’s 65 degrees (18 celcius) today in San Francisco?

Oh, I almost forgot to mention what talks I submitted. All of them will have an eBay theme, but none of them are 100% eBay advertisements:

• Consuming Web Services Using PHP 5
• Dirty secrets of PHP 5’s ext/soap extension
• Abracadabra and hocus pocus: Magical methods and PHP 5

I really like my abstract for the that last talk:

PHP 5 provides a number of so-called “magical methods,” methods that are automagically invoked to secretly manipulate objects. These __methods() are cool, but when, if ever, are they actually useful? Using an eBay Web services SOAP client as my example, I’ll demonstrate how a little slight-of-hand and misdirection leads to shorter and more intuitive code.

Right now, my eBaySOAP code uses __construct(), __set()/__get(), __call(), __isset(), __toString(), and the IteratorAggregate and ArrayAccess interfaces. If I can get Dmitry to add the hook he promised to ext/soap, I’ll also add __wakeup(). I’m sure there are a few more things I can do, but the trick is to only implement useful and intuitive methods, so we’ll see.

Like all Web 2.0 concepts, it’s in perpetual beta. (Why does “perpetual beta” seem like the Web 2.0 phrase for Web 1.0’s “Under Construction” image?) Thanks to a helpful prod, I sat down this morning and fixed the outstanding IE bugs, so now it works in IE, Firefox, and Safari. That means I can officially blog about it.

For those of you interested in the technical details, the backend code is written in PHP 5. I’m using the ext/soap extension to talk with eBay Web services and PEAR’s HTML_QuickForm, HTML_Javascript, and Date packages. I tried to use HTML_AJAX, but it was buggy when I first tried it; I see there have been many recent updates, so I should look again.

Not surprisingly, writing the PHP part was pretty easy. It was the JavaScript code that took forever and a day to write and debug. Many thanks to the QuirksMode Web site for documenting cross-browser woes.

Please check out the site and let me know what you think.

Therefore, I’ll pull out a few lines, combine that with some hand waving, and just hope for the best. Here’s the before:

$wsdl = 'http://developer.ebay.com/webservices/latest/eBaySvc.wsdl';
$client = new SoapClient($wsdl);

$params = array('Query' => 'ipod');
$results = $client->GetSearchResults($params);

foreach ($results->SearchResultItemArray->SearchResultItem as $item) {
  print $item->Item->Title . "\n";
}

Without the classmap option, I create a SoapClient, make my request, and then iterate through the results to print out the titles of the matching items. This isn’t complex; however, the iteration is a little klunky due to limitations of SOAP and the design of eBay’s Web service.

For example, the SearchResultItemArray only contains SearchResultItem, so it’s kludgy to reference SearchResultItemArray->SearchResultItem. Likewise, when I’m just getting a quick dump of Item information, it’s not so nice to specifically access the Title element.

By defining a couple of classes and telling the SoapClient object map them to the return data, I can clean this up:

class eBaySearchResultItemArrayType implements IteratorAggregate {
  public function getIterator( ) {
    return new ArrayObject($this->SearchResultItem);
  }
}

class eBaySearchResultItemType {
  public function __toString() {
    return $this->Item->Title . "\n";
  }
}

$wsdl = 'http://developer.ebay.com/webservices/latest/eBaySvc.wsdl';
$options = array('classmap' => array(
  'SearchResultItemArrayType' => 'eBaySearchResultItemArrayType',
  'SearchResultItemType' => 'eBaySearchResultItemType',
  ),
);

$client = new SoapClient($wsdl, $options);

$params = array('Query' => 'ipod');
$results = $client->GetSearchResults($params);

foreach ($results->SearchResultItemArray as $item) {
  print $item;
}

To solve my first problem, the iteration, I make eBaySearchResultItemArrayType implement the IteratorAggregate interface. When a PHP 5 class implements this interface, PHP will invoke the getIterator() method during a foreach loop.

In this case, I return $this->SearchResultItem, wrapping it inside an ArrayObject to make the array iterable.

For the pretty-printing issue, I define a __toString() method inside of eBaySearchResultItemType. Now, when I print an instance of this class, PHP calls that method instead.

With my classes defined, I use the classmap option to map the PHP classes to the SOAP complexTypes, and pass this mapping along as part of the second parameter to the SoapClient constructor.

Once this is set up, everything else in the request is identical. However, when I print out the results, the syntax is clean:

foreach ($results->SearchResultItemArray as $item) {
  print $item;
}

At one level, this is just syntax and icing. However, I don’t think you should dismiss syntax with a wave of your hand. To quote Sam Ruby on C# and LINQ:

[S]yntax matters. Very much so.

So, I am convinced that this is a good thing to spend time on. There are a couple other tricks I’ve pulled out, such as:

class eBayFeesType implements ArrayAccess {

  public function offsetGet($offset) {
    foreach ($this->Fee as $value) {
      if ($value->Name == $offset) {
        return $value;
      }
    }
  }

  /* and the other interface methods... */
}

class eBayFeeType {
  public function __toString() {
    return (string) $this->Fee->_;
  }
}

This lets me do:

echo "Listing fee is: ", $results->Fees['ListingFee'], "\n";

Which I must say is far nicer than either iterating in place or even calling out to a utility method.

I was interested to discover that I needed to manually cast $this->Fee->_ to a string because I thought it was a string. Actually, it is a float, and PHP won’t autocast floats to strings in this instance.

Personally, I think if PHP should autocast here, but I can see the logic. If you’re promising to return a string, you should actually return one.

At first, I was writing each class by hand. But that got boring and wasn’t scalable. Therefore, my new goal is to automate this process. I am writing a script to read the WSDL file, parse out the complexTypes, and then convert them to PHP classes.

My original script was using the SoapClient::__getTypes() method as a pre-processor, but I needed to parse that output again to get it into a usable format. After a little digging, I discovered that PEAR::SOAP implements its own parsing routines and gives me a far more flexible PHP data structure to manipulate. So, I am going in that direction instead.

Since this is a one-time action, speed isn’t vital, so it’s okay that PEAR::SOAP is written in PHP.

If you’re interested in more details on these new PHP 5 features, they’re documented in the PHP Manual. Alternatively, in a shameless plug, you can check out my book Upgrading to PHP 5.