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 there’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.

Dev: 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.

(time passes)

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.