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.

Looking at the Table of Contents, I’m particularly interested in “Appendix A: HTTP status codes and when to use each one.” (Yes, I am serious.)

When I designed “Dude, Where’s My Used Car,” my mashup between eBay Motors and Google Maps, I churned through a number of different ways to signal failure. My biggest issue is that there’s so many places my request can fail, I’m not sure how to “correctly” represent that back inside my mashup.

For example, in response to a user-generated action (such as filling out a form and clicking submit), my mashup initiates a HTTP GET AJAX request (well, AJAJ because I’m using JSON instead of XML) which hits my web server. I then use PHP to parse the request, generate a corresponding SOAP request to eBay’s web service gateway, wait for result, pick it apart and convert the bits I want to JSON. This data is then passed back to the browser, where I (well, Dojo, actually) evals it.

When everything works, everything works.

But what happens when the user enters an invalid ZIP Code? eBay will return an error, and I’d like to proxy this back to the application, so I can toss up a message.

Should I return 200 OK and pass back the message? That’s one option, but I’d prefer not to need to check the data structure to see if I got the normal data I expected or some nasty error instead.

Besides, Dojo lets me specify a separate error handler callback function. It seems a cleaner design to handle all the errors there. But then I can’t return 200. What to use instead? 400 Bad Request?

Then there’s cases where the error is not the user’s fault, but either my fault or eBay’s fault. What should I do if eBay returns a SOAP envelope my PHP script can’t parse? 502 Bad Gateway? Or if the eBay server returns a SOAP Fault? The same 500 Internal Server Error I got back from eBay?

Should I not let my web server’s interaction with eBay bleed back into browser?

Here’s another example: when eBay’s server is too busy, it returns Error Code 10007. I can retry (and hopefully fix the problem) inside of my PHP script without even needing to message back to the browser. But if I did ultimately give up retrying, should I pass back 503 Service Unavailable? Am I on the hook for translating between SOAP and REST in my server-side proxy PHP script?

Maybe I can use 4xx codes for problems which are “user generated” in some form. These are things which require the user to take an action to remedy. And for things which are broken but otherwise outside of the control of the user (such as my SOAP client being unable to understand eBay’s SOAP response) I can use 5xx.

I actually like this idea, but I’m wondering if there’s a “standard” way to indicate errors and failures in a AJAX application. I can’t find one, but I’m not very familiar with what’s out there.

PS: My vote is to leave off the “With Ruby” part of the title, and go with plain “REST Web Services”.