There has been a long running debate in the Application Platform Services Group here at Burton Group between the REST people on one side and the SOAP people on the other. For the most part it mirrors the external debate. In one recent exchange, while discussing the complexity of SOAP and the web services framework, the SOAP side said, “Before all of the WS-* stuff, SOAP was actually simple. That’s what the ‘S’ stood for.”
And now a history lesson. It’s the year 2000, a harried developer has a problem
Developer: So, my boss was playing golf this weekend, and now I have to ‘quote, unquote’ SOAP-enable the enterprise, but I don’t know what SOAP is. Can you help, SOAP Guy?
SOAP Guy: Sure thing. First, SOAP stands for Simple Object Access Protocol.
Dev: So it’s simple?
SG: Simple as Sunday, my friend.
Dev: Okay, lay it on me.
SG: Well, just like it says in the name, SOAP is used for accessing remote objects.
Dev: Like CORBA?
SG: Exactly like CORBA, only simpler. Instead of some complex transport protocol that no one will let traverse a firewall, we use HTTP. And instead of some binary message format we use XML.
Dev: I’m intrigued. Show me how it works.
SG: Sure thing. First ther’s the SOAP envelope. It’s pretty simple. It’s just an XML document consisting of a header and a body. And in the body you make your RPC call.
Dev: So this is all about RPCs?
SG: Absolutely. As I was saying, you make your RPC call by putting the method name and its arguments in the body. The method name is the outermost element and each sub-element is a parameter. And all the parameters can be typed as specified right here in Section 5 of the specification.
Dev: (reads Section 5) Okay, that’s not too bad.
SG: Now, when your service is deployed, you specify the endpoint.
SG: Endpoint, the address of the service. You POST your SOAP envelope to the endpoint’s URL.
Dev: What happens if I GET the endpoint’s URL?
SG: Don’t know. Using GET is undefined.
Dev: Hrrm. And what happens if I move the service to a different endpoint? Do I get a 301 back?
SG: No. SOAP doesn’t really use HTTP response codes.
Dev: So, when you said SOAP uses HTTP, what you meant to say is SOAP tunnels over HTTP.
SG: Well, ‘tunnel’ is such an ugly word. We prefer to say SOAP is transport agnostic.
Dev: But HTTP isn’t a transport, it’s an application protocol. Anyway, what other “transports” does SOAP support?
SG: Well, officially none. But you can potentially support any of ‘em. And there’s lots of platforms that support JMS, and FTP, and SMTP.
Dev: Does anyone actually use these other transports?
SG: Uhm, no. But the point is you can.
Dev: Fine. How ’bout this SOAPAction HTTP header, what’s that for?
SG: To be honest, no one’s really sure.
Dev: And these ‘actor’ and ‘mustUnderstand’ attributes, does anyone use those?
SG: No. Not really. Just ignore those.
Dev: All right, let me give it a shot.
Dev: Well, I could mostly make things work, but only if I stick with one SOAP stack. Also, I can’t say I like the idea of remote procedure calls and serializing objects.
SG: Remote procedure calls! Serialized objects! Where did you get the impression that SOAP was about RPCs? SOAP is all about document-based message passing, my friend.
Dev: But you just said –
SG: Forget what I said. From here on in we pass around coarse-grained messages — you like that term, ‘coarse-grained?’ Messages that conform to an XML Schema. We call the new style Document/Literal and the old style RPC/Encoded.
Dev: XML Schema?
SG: Oh, it’s all the rage. Next big thing. Take a look.
Dev: (Reads XML Schema spec). Saints preserve us! Alexander the Great couldn’t unravel that.
SG: Don’t worry about it. Your tools will create the schema for you. Really, its all about the tooling.
Dev: How are the tools gonna do that?
SG: Well, they will reflect on your code (if possible) and autogenerate a compliant schema.
Dev: Reflect on my code? I thought it was all about documents, not serialized objects.
SG: Didn’t you hear me? It’s all about the tools. Anyway, we can’t expect you to write XML Schema and WSDL by hand. Besides, its just plumbing. You don’t need to see it.
Dev: Whoa, back up. What was that word? Wizzdle?
SG: Oh, haven’t I mentioned WSDL? W-S-D-L. Web Services Description Language. It’s how you specify the data types, parameter lists, operation names, transport bindings, and the endpoint URI, so that client developers can access your service. Check it out.
Dev: (Reads WSDL spec). I trust that the guys who wrote this have been shot. It’s not even internally consistent. And what’s with all this HTTP GET bindings. I thought GET was undefined.
SG: Don’t worry about that. Nobody uses that. Anyway, your tools will generate a WSDL, and in the WSDL will be the schema.
Dev: But shouldn’t it be the other way ’round? Shouldn’t I design the contract first and then generate the code?
SG: Well, yeah, I guess that sounds right in principle. But that’s not so easy to do, and very few SOAP stacks support WSDL-first development. Just let the tools worry about it.
Dev: One more question. If we’re now passing around XML Schema compliant messages, where do you specify the operation name?
SG: Well, remember that SOAPAction HTTP header? Most people are putting it there.
Dev: Most people?
SG: Well, this new style isn’t actually written down anywhere.
Dev: I’ll also note that your entire industry is built around ambiguous, sometimes erroneous, and definitely not standardized specifications. In fact, the SOAP and WSDL specs are just W3C Notes, not even working drafts.
SG: We’re working on that.
Dev: Will this give me the interoperability I’ve been promised?
Dev: I’ll try it out.
Dev: This is getting ugly. The WSDL my tools generated can’t be consumed by the tools my partners use. Not only that, the schemas it generates are impenetrable and can’t be reused. And no tool seems to have agreed on how best to handle the SOAPAction header.
SG: Sorry to hear that, buddy. On the bright side, nobody uses the Doc/Lit style anymore. In order to get transport independence back we’re all using wrapped-doc/lit now. Doesn’t that sound cool: wrapped-doc/lit?
Dev: What’s that?
SG: Well, it’s just like Doc/Lit, but you take the whole message and wrap it in an element that has the same name as the operation. Now the operation name is back in the message where it belongs.
Dev: Okay, where’s the spec on this?
SG: Oh, there is no spec. This is just what Microsoft seems to be doing. Looked like a good idea, so now all the cool kids are doing it. However, there is this new thing. I think you’re gonna like it. It’s called the Web Services Interoperability Group, or the WS-I. What they’re doing is trying to remove a lot of the ambiguity in the SOAP and WSDL specs. I know how you like specs.
Dev: So, in other words, the specs were so bad you need a standards body to standardize the standards. Lord. Well, will this solve my interoperability problems?
SG: Oh, yeah. So long as you use a WS-I compliant SOAP stack, avoid using 8/10ths of XML Schema, don’t use any unusual data types, and don’t count on working with WebSphere and Apache Axis.
Dev: And is wrapped-doc/lit explained in there?
SG: Ermm, no. But that’s okay, you’re tools understand it. Most of them, anyway.
Dev: Let me sum up. The definition of SOAP is in constant flux, SOAP is anything but simple, and it is no longer meant for accessing objects-even though that’s what all the tools still do.
SG: That’s about right, but we’re way ahead of you on this. We’ve deprecated the meaning of the SOAP acronym.
Dev: Really! What does it stand for now?
SG: Let me tell you about UDDI.
I see that Duncan Cragg has beat me to the punch by also using the dialog format for his most recent REST/SOAP related post. I take solace in the fact that this conceit has been used since the days of Socrates.