Let me explain. Imagine you have this service that would return a stock quote given a stock symbol. It sends some data to the Nasdaq web page and scrapes the returned HTML to give you the result. Now, to allow other developers to use it inside of their applications, you might make this into a component that uses the Internet to access the quote information. Works great, except suddenly Nasdaq changed their web page layout. You're going to have to redo all the logic and send an update to every single developer that used your component! And they have update all THEIR users. If this happens with any regularity, you're going to get some really furious developers. And we all know how dangerous developers can be. You don't want to end up with a printout of a horse's head in your bed, do you?

What's the alternative? Think about this...all you need is to expose a function that takes a stock symbol (string) and return a stock quote (float or double). So, wouldn't it be easy if you simply allowed your developers to somehow call this function over the internet? Great! So what, you say, we've had COM and Corba and Java that has done this for ages...that's true, but they have their disadvantages. With COM, remote configuration is not trivial. Also you have to open so many ports on your firewall, something sysadmins are not too keen to do. You're going to have to forget about non Windows users. Linux users do need stock quotes too, you know.

Seems like Linux users have a hope if you're using DCOM, check out http://www.idevresource.com/com/library/articles/comonlinux.asp - Thanks to Alessandro Federici for mentioning this!

I don't know much about Corba or Java, so I'll leave it as an exercise to the reader to figure out the disadvantages there. (I just love it that I can do this)

SOAP is a standard (which means that everyone will do things differently) that allows you to describe such a "remote" function call, and the way you would return the results. So what you would do is to put your Stock Quote function in an application that's somehow accessible over a network (an ISAPI app on your web server, for instance) and it would get calls that are "SOAP formatted". You would then validate the inputs, run your function and return the results in another SOAP formatted packet. And this can be done even over HTTP, so you don't have to open a few dozen ports on your firewall. Simple isn't it?

What this paper is about...

This is the first of a series of papers on SOAP that we at Agni Software are writing. This particular paper will concentrate on giving you an idea of what SOAP is about, and how you can write applications in Delphi 6 that will call SOAP servers. In the next paper, I will describe how you can write your own Soap Servers and Clients, using Delphi.

In future articles I will describe how to make your SOAP server accessible to users of other SOAP toolkits like MS SOAP, .NET, PocketSoap and Apache.

Soap and XML

In order to make SOAP not so simple for you and I, we need to add XML. So instead of a function name and parameters, we now need to have a complicated XML envelope that is designed to confuse you. But don't get scared yet. There's more, and you should see the full picture before you start thinking this is complicated. (It is.)

If you don't know what XML is, stop right here and read my paper on XML at http://www.agnisoft.com/white_papers/xml_delphi.asp.

All Soap packets are formatted as XML. What does this mean? Let's see. Take a look at this function: (Pascal)

Looks great, but the problem is - it's Pascal. How does a Java programmer benefit by giving this seemingly simple definition? Or someone who works on VB? We need something everyone can understand, even VB users. So we give them XML containing the same information (parameters, stock quote values etc You create a SOAP "envelope" - which is basically your function call, wrapped as XML so that any application on any platform can understand it. Let's now see a SOAP call looks like:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema" > <SOAP-ENV:Body> <ns1:GetStockQuote xmlns:ns1="urn:xmethods-quotes"> <SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <symbol xsi:type="xsd:string">IBM</symbol> </ns1:GetStockQuote> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

How informative! We see here that SOAP is getting more and more simple. Well, that was the fun part. Now I'm going to tell you how to understand this soap call, because, well, because you're reading this and I'm writing this and I can pretty well write what I want to.

The Tags Revealed

The first "tag" you see is the <SOAP-ENV:Envelope ... > tag. This tag is an outer shell to the SOAP packet, giving you various namespace declarations you don't care about, but your average programming language or parser does. The namespaces are defined so that further "prefixes" to tags such as "SOAP-ENV:" or "xsd:" make sense to a parser.

The next tag is <SOAP-ENV:Body> . (We've skipped a tag that is not shown here - the <SOAP-ENV:Header> tag. It's not in this particular Soap envelope, but if you want to read more about it, go to the SOAP specification at http://www.w3.org/TR/SOAP/) The <SOAP-ENV:Body> tag is a placeholder that starts off the actual SOAP call.

Coming next is the <ns1:GetStockQuote ...> tag. The tag name, GetStockQuote, is the function to be called. In Soap lingo, this is called an operation. So GetStockQuote is the operation that needs to be executed. ns1 is a namespace, which points to urn:xmethods-quotes in this case.

A small note about namespaces: A namespace is a way to qualify an XML tag - for instance you cannot have two variables with the same name in one procedure, but it's ok if they're in two different procedures. So the procedure is a "namespace" - all names are unique within it. Similarly, XML tags can be scoped inside namespaces, so that, given a namespace and a tag name, you can uniquely identify and find a tag. We will point a namespace to a URI (Uniform Resource Identifier), in order to make sure that "my NS1 is not the same as yours". In our example above, NS1 is the alias for a namespace which points to urn:xmethods-quotes.

You'll also notice an encodingStyle attribute - this attribute specifies how a soap call is serialized. Within the <GetStockQuote> tag lie the parameters. In our simple case, we only have one parameter. Which is the <symbol> tag. You'll notice that there's this extra little thing next to the tag :

xsi:type="xsd:string"

This is approximately how XML defines types. (Note the clever use of the word "approximately" when making a absurdly general statement about a technology that might mutate the minute I put this paper on the web) What this particular statement means is: the type, as defined in the xsi namespace, which you would have noticed is declared in the <SOAP-ENV:Envelope> tag, is xsd:string. Which in turn is a string, as defined in the xsd namespace, again defined earlier. (I'm sure Lawyers love this stuff)

Inside of the <symbol> tag there's the boring little "IBM". This is the value of the parameter symbol to the GetStockQuote function.

Beyond this, like good people, we close our XML tags.

That's about the SOAP packet, which defines a "call" to a SOAP server. The soap server, using the support of complex XML parsers, nuclear missiles and the mir space station, decodes the call and figures that you want to get a stock quote. It then quickly fetches the stock quote and sends you back a packet like so:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> <SOAP-ENV:Body> <m:GetStockQuoteResponse xmlns:m="urn:xmethods-quotes"> <Price>34.5</Price> </m:GetStockQuoteResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

This, after removing all the envelopes, the gift-wrap and the embellishments, simply tells you that the price of the IBM stock was 34.5.

Most commercial servers would return a LOT more information than just that, of course, like in what currency, last traded price etc. And would perhaps return a more accurate value of the IBM stock.

So we now know what a soap server expects, and what to send back. Now HOW do we send such information? You could use any transport. The most well discussed case is HTTP. I'm not going to explain what that is, except it's what your web browser uses to communicate with those web sites you go to.

You would make an HTTP request such as:

POST /StockQuote HTTP/1.1 Host: www.stockquoteserver.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "Some-URI" ...the soap request packet here...

The only other point of significance here is the SoapAction header. This header indicates the intent of a request, and it is mandatory. Each SOAP server could have multiple functions, and it could decide to use the SoapAction header to figure out which function is being called. Also, firewalls and server multiplexers can filter content using this header.

The soap response from the HTTP server will be as follows:

HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn ...Soap Response packet here...

Why HTTP? For one, network administrators do not have to worry about opening separate ports for SOAP calls...a web server would do the job, and port 80 is usually opened to the world to handle incoming web requests. The other advantage is that web servers are usually extensible using CGI, ISAPI or other native modules. This extensibility allows us to write a module that will handle a SOAP request, while not affecting any other web content.

That's all for now, folks

This, I hope, has been a reasonably understandable description of SOAP. If you're still here, and want to know more, we'll have some more articles on Soap, WSDL and other such four letter words coming up soon.

Meanwhile, feel free to mail me with your questions, suggestions and any praise. If you think this article sucks, email me at yousuck@nowhere.com. All other mail can be sent to shenoy@agnisoft.com.