intertwingly

By Sam Ruby, January 25, 2002.

The name of the protocol is Simple Object Access Protocol.  This document describes explores the relationship between a SOAP message and the object it accesses.

Request Example 

Here's an example of a SOAP request taken from the BDG:

POST /examples HTTP/1.1
User-Agent: Radio UserLand/7.0 (WinNT)
Host: localhost:81
Content-Type: text/xml; charset=utf-8
Content-length: 474
SOAPAction: "/examples"

<?xml version="1.0"?>
<SOAP-ENV:Envelope
  SOAP-ENV:encodingStyle="http://soap/encoding/"
  xmlns:SOAP-ENC="http://soap/encoding/"
  xmlns:SOAP-ENV="http://soap/envelope/"
  xmlns:xsd="http://1999/XMLSchema"
  xmlns:xsi="http://1999/XMLSchema-instance">
  <SOAP-ENV:Body>
    <m:getStateName xmlns:m="http://www.soapware.org/">
      <statenum xsi:type="xsd:int">41</statenum>
    </m:getStateName>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Local Procedure Call Equivalent 

A local procedure call equivalent to this might be (depending on your choice of language):

examples.getStateName(41);

If you look at the message, you can readily see where the 41 came from.  And where the getStateName came from.  But where did the "examples" come from?  How does the recipient of the SOAP message know what object to access?  If you take a look at the SOAP specification, you will see that it doesn't tell you.  In fact, it doesn't tell you anything about how the message is to be interpreted, merely how the message is to be formed.  Lets look at three different answers.

UserLand Frontier 

It is my understanding that UserLand Frontier selects the object based on the SOAPAction.  In the message above, the action is "/examples".  The mapping of this to the object in question is pretty straightforward.  Straightforward is good when you are publishing a web service.

Apache SOAP 

Look at the XML element which starts out with m:getStateName.  The "m" prefix identifies a namespace.  This example used m, but pretty much any string could have been used.  For that matter, it could have been 

<examples:getStateName xmlns:examples="http://www.soapware.org/">

When you deploy a service using Apache SOAP, you provide a mapping between the namespace and a Java object.  This makes it easy to implement any SOAP API that anybody proposes.  Easy is good.  Note that this is the other direction than in the straightforward publishing direction I described in the Frontier case.  When you have an API that multiple vendors implement, there will be at most one vendor for which the service came first.  For all the rest, the API will come first.  But I have made too big of a deal of this point already, in most cases, this will not be a problem.

A more subtle and important reason for this is that while SOAP over HTTP is likely to be far and away the most common case, HTTP is not the only protocol over which SOAP messages are received.  In the example above, everything above the blank line is HTTP.  To be protocol independent, there needs to be a way to determine the object to be accessed using only the information below the blank line.

Microsoft ASP.Net 

I believe that ASP.Net keys initially off of the URI.  One thing that is perfectly clear and indisputable is that every SOAP message that is sent to a predefined endpoint.  Furthermore, there is a preexisting infrastructure that allows for the mapping of requests based on the URI to either a static or dynamic page on disk.  This typically is very straightforward, with the path mapping by default to a directory.

Above, I said "I believe".  I actually have no way of knowing.  In fact, Microsoft could change this at any point and I would have no way of telling.  For, you see, the ASP.Net implementation actually validates all three.  The specification for a service includes a URI, a soap action, and a namespace.  When defining a service, the namespace and soap action reasonably default.  When using their development tool you will find it easy to override the defaults.  In fact, the tool will encourage you to override the default for the namespace, and then base the default soap action on that namespace.

Which Is Right? 

Three implementations.  Three approaches.  Which is right?  Frankly, SOAP doesn't care.  When a SOAP client forms a request, it must specify all three pieces of data correctly.

Much of the early interop problems we encountered were due to platform vendors choosing and supporting only one or two of these three approaches, and on the server side ignoring the data that didn't matter to them.  Ignoring the data is not a problem, but if the data that others expect is not sent then that that client "does not play well with others".

FYI: Apache Axis can be configured to try all three approaches, in the order that you desire, and will continue until it finds a match.  Our recommendation is that the URI be used.

Conclusion 

In order to correctly and interoperably access a SOAP service, a client must specify three pieces of information in order to identify the object to be accessed.  Correspondingly, in order for a web service to be published, all three pieces should be specified.  A given service implementation may chose to ignore or validate any of these data.

Editorial 

In many cases options are good.  In other cases, they simply increase complexity, implementation costs, and create unnecessary interoperability issues.  In the W3C there has been discussions about removing, or at least deprecating, the use of SOAPAction.  As you might imagine, this is controversial.

This is a recurring theme in the current set of web services standards.  The standards themselves provide options and that is good.  As a community, we need to formulate a set of guidelines of "best practices" for interopable usage.