It’s just data


Leonard Richardson: Are all these architectures mutual opposites, or points on a gradient?

My answer: neither.  But before we get there, indulge me for a moment.

Let’s start with  If you go to that page, actions made available to you include a FlightSearchUpdatePreferredCities, and the ability to request gatesTimesStatus.

Each are done with HTML forms.  Each are done with HTTP POST, even the queries.  Each are request/response.  Each passes a number of input parameters along with the request.  A common paradigm for HTML forms is for buttons to be used to determine the action taken — and this is also transmitted as an input parameter value.

This should sound familiar.  These are forms of remote procedure calls, implemented using HTML over HTTP.  Request parameters, and even the action selected, may be included in either the URI itself, or in the POST body.  Both approaches are common practice, and both are well supported by the various browsers and servers that implement these protocols.

Is using POST for such actions a best practice?  Not if you want to be able to bookmark a search result.  But given the way that this particular application uses URL rewriting techniques to implement a session, bookmarking isn’t really practical for this service.  That’s a trade-off that they can chose to make.  After all, using HTTP GET involves a different set of trade-offs.

Now, lets look at an XHTML document, containing an SVG circle:

    "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
<html xmlns=''>
    <svg xmlns="">
      <circle fill="#009" r="45" cx="50" cy="50"/>

This document is described by a DTD, contains a head with some metadata, and a body.  It can be processed by a DTD aware tool, can be treated as Plain Old XML, produced by a template, or simply entered into notepad.  I created it using vi.

Now lest take a look at a SOAP document, containing the same SVG circle and a somewhat randomly chosen header:

<Envelope xmlns="">
    <path xmlns="">
    <svg xmlns="">
      <circle fill="#009" r="45" cx="50" cy="50"/>

First note that there is no DTD provided (in fact, such is not allowed), nor is there any schema references (such is entirely optional).  Like the XHTML document above, it also contains a Header with some metadata and a Body.  If a separate WSDL document were provided, this document could be processed by an XML Schema aware tool, but it can also be treated as Plain Old XML, or produced by a template, or simply entered into notepad.  Again, I created this particular document using vi.

Contrary to what some will lead you to believe, I submit that it is possible for a query to be simultaneously SOAP, REST, RPC, POX, and transmitted using HTTP POST.  And all this could be done with or without a WSDL document or an XML schema.  Furthermore, both ends of the wire don’t have to agree.  I can create a request using POX techniques and send it to an interface fully generated from a WSDL document containing a full XML schema and implemented using the Windows Communication Foundation.

I maintain that POX is not an information format style, but rather a set of techniques for producing and consuming XML.

In any case, the point is that doing any of the above involves trade-offs.  Often we are talking about trade-offs that you are not even aware that you are making.  Again, one such trade-off is “if your application routes based on either an HTTP header or data within the payload, then your users will not be able to bookmark the request”.  Another is “if you implement unsafe operations using HTTP GET, bad things will happen if your pages get spidered”.

Yet another trade-off I consistently see is the desire to treat XML as merely a serialization format, not as a document lovingly crafted by humans.  Ask current versions of Microsoft Word to save a document as HTML, and you will often get a document that simply is not fit for human consumption.  You can achieve similar results using yacccamping.rb proves that a certain class of humans can also produce such output too.

CORBA is based on the notion of generating implementation from IDL documents.  Conventional wisdom is that this works best if both ends of the wire are based on CORBA implementations from the same vendor.  The situation is a bit better in WS-*, interop works best when the WSDL is generated from an implementation and if the vendors who provide each end of the wire have actively participated in pairwise interop testing.  Those that merely attempt to produce compliant WSDL based on the available specifications often find problems such as these.  But the siren call for viewing the programmable web as merely a serialization format seems unstoppable: the current incarnation is called WADL.

Despite using HTTP POST, the example above is not only RESTful, but it is of the web.  If you were to map out the entire application, you would find a state machine, one that humans or bots alike can navigate by real or virtual mouse clicks.  The nodes in the state machine are mapped to URIs.  The URIs are connected via hypertext links.  These links generally are not found in HTTP headers, but in the payload of the documents themselves.  This approach is called Representational State Transfer.

BPEL4WS using SOAP is an alternative.  An alternative that is typically web in name only.  The messages involved don’t tend to contain anything resembling a hypertext link.  State is not transferred in representations.  What you have instead is a discrete set of endpoints whose activity is choreographed by an external agent, one that manages the overall state of the system.  A different approach.  One that reflects a different set of trade-offs.

Finally, Sanjiva brought up WS-Security.  If you find yourself needing to sign and encrypt SOAP requests and responses using X509 certificates, you will find that it is implemented interoperably by a handful of vendors.  Others may find that they can achieve the levels of security they need using PGP.  And despite the fact that it is limited to being point to point, finds SSL more than sufficient for transferring credit card information privately and securely.

It is my hope that this book will be an eye-opener to many.