biotext.org.uk

Update (1-Nov-09): Since writing this post nearly a year ago, I’ve come to realise that I was labouring under quite a few misconceptions myself, about REST. Spotting them all is left as an exercise for the reader. But I’d rather leave it here with this caveat, than remove it and pretend I knew better all along…

Michael Little at Fliquid Studios recently posted an interesting comparison of SOAP vs REST which may have accidentally perpetuated a misconception about SOAP that I believe is fairly common. This post is a response to that and a expanded version of a comment I left on Michael’s site.

The confusion arises from the difference between the communication layer (SOAP) and the databinding layer (aka marshalling/unmarshalling) which is responsible for mediating between language-native data structures and XML. Michael is writing from a PHP point of view, and I’m not sure what PHP SOAP toolkits are like in this regard, but fortunately in the Java world the distinction between the two is made clear, and we have various options for each — although JAX-WS for SOAP and JAXB for databinding are the industry standard specifications.

For example, Michael says:

… the way the PHP SoapServer class handles arrays of data is (or was last time I checked) incompatible with the way an ASP.NET SOAP client handles them…

While this may well be true, it’s also somewhat tangential to a general discussion of the differences between SOAP and REST, and seems to chime with a sentiment I’ve detected elsewhere that REST is easier because it’s ‘just XML’ — or whatever other method for structuring the data you choose to use instead. The translation of XML data into arrays is the responsibility of the databinding layer, and nothing to do with SOAP per se. Incompatibilities between different approaches to marshalling and unmarshalling would also be an issue if one wanted to use a databinding layer over REST.

Databinding is not part of the SOAP spec. At their heart, SOAP messages are also just XML documents, exactly like REST, and there’s always the option of parsing the XML yourself, exactly as you would with REST. We do this extensively in the FuncNet project, for performance reasons. It can also be useful, as Michael’s article indirectly suggests, for sidestepping compatibility issues — because every language can read/write XML.

You can even use SOAP to send/receive arbitrary non-XML data, e.g. via attachments or CDATA or large strings… e.g. plain text, JSON etc. Soaplab2 for example sends the results of SOAP-wrapped programs as-is, as large chunks of text.

Michael replied to me that his article “is intended to be related to the practical implementation of SOAP/REST in PHP”, but I thought it worth expanding on this point nonetheless, as he does also mention at the start that the content is hopefully useful to developers of other languages. Any decent SOAP service toolkit should give you the option to receive the whole request as XML, and/or generate raw XML for the response yourself. The same is true (in reverse obviously) for SOAP clients. These features are something worth checking for before committing to one stack or another, where a ’stack’ includes not just the SOAP libraries themselves but the language and environment that they’re built on. Tight coupling between a communication layer and a databinding layer isn’t a good sign and might, as Michael’s note about of SoapServer shows, reduce your interoperability options.

So if you are developing services that parse and generate XML directly, what advantage is there to using SOAP and WSDL over the simpler REST approach? Well, many SOAP/WSDL features are unrelated to databinding, for example mature tool support, schema validation, formally-defined contracts with documentation right down to the level of individual parameters, automatic service discovery via registries, and semantic annotation with extensions like SAWSDL. But more importantly, just because you may not be using databinding on the server side, doesn’t mean your consumers can’t.

Of course there are benefits to REST too, primarily ease of development, simplicity and elegance, and lower overhead — important if you’re sending/receiving lots of small messages. And there’s nothing to stop you using databinding technology to marshal or unmarshal REST messages too. It’s important to remember REST and SOAP are both essentially protocols for sending and/or receiving documents, and in that sense, they aren’t really all that different.