The SOAP XML Document

SOAP Documents and Transport Bindings

In addition to the XML in a SOAP request, there is also a header outside of the XML that is specific for the protocol being used, such as HTTP. The information in this header contains the response code, the version of the protocol being used, the content type of the message, and perhaps other vendor-specific information. The next section shows the type of header needed for an HTTP request.

HTTP Request

The following example shows the Stock Quote SOAP Request with its HTTP header. This information tells the server receiving the request where to send the request based on the information here.

The first line states that the information is being posted to the Stock Quotes Web Service using HTTP Version 1.0. The host information on the next line tells the request where on the World Wide Web (WWW) the service exists. The Content-Type definition shows what type of information is in the request. In this case, it is XML. Content-length tells how many characters exist in the request. SOAP action contains the namespace for this particular Web Service (http://www.advocatemedia. com/webservices/) and the name of the particular method responsible for processing the data (getquote).

POST /stockquotes HTTP/1.1 Host: www.advocatemedia.com:80 Content-Type: text/xml; charset=utf-8 Content-Length: 482 SOAPAction: "http://www.advocatemedia.com/webservices/getquote" <?xml version='1.0' ?> <env:Envelope       xmlns:env="http://www.w3.org/2001/12/SOAP-envelope"      xmlns:xsd="http://www.w3.org/1999/XMLSchema"      xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"      xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/SOAP/encoding/"      xmlns:stockquote="http://advocatemedia.com/examples"> <env:Body>   <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[3]">     <stockquote:symbol>C</stockquote:symbol>     <stockquote:symbol>GE</stockquote:symbol>     <stockquote:symbol>DJI</stockquote:symbol>   </SOAP-ENC:Array>  </env:Body> </env:Envelope>

The header is what makes this example go from an XML document to an actual SOAP request.

HTTP Response

The following code is a possible response to the Stock Quote Example. The header contains information similar to the request, but not as much information is needed in the response because the connection still knows where the client resides.

The first part of the header indicates that the response comes back via HTTP Version 1.1 and that the status is 200 (which means complete) and OK meaning the data processed correctly. The second line shows that now the request and response are complete the connection is closed. The final two lines are just like the request where Content-Length indicates the number of characters in the message and Content-Type indicates that the response contains XML.

HTTP/1.1 200 OK Connection: close Content-Length: 659 Content-Type: text/xml; charset=utf-8 <?xml version='1.0' ?> <env:Envelope   xmlns:env="http://www.w3.org/2001/12/SOAP-envelope"   xmlns:xsd="http://www.w3.org/1999/XMLSchema"   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"   xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/SOAP/encoding/"   xmlns:stockquote="http://advocatemedia.com/examples">   <env:Body>       <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:int[3]">         <stockquote:price          stockquote:symbol="C">53.21</stockquote:price>         <stockquote:price          stockquote:symbol="GE">48.00</stockquote:price>         <stockquote:price           stockquote:symbol="DJI">9500</stockquote:price>       </SOAP-ENC:Array>   </env:Body> </env:Envelope>

Notice that the response uses a SOAP array to return data.

An Example of a SOAP Error

If there’s an error, like passing a nonexistent stock symbol, the SOAP standard needs to have a mechanism to deal with that. The following example shows what happens with both the XML document and the server header.

The HTTP header indicates that an error occurred during the request. Not only are there the words “Server Error” but also code 500 indicates that there was an error. Within the XML, there are two tags to indicate what happened. The faultcode element contains information that the software can parse and understand what happened. The faultstring element tells the programmer what happened. The following, for example, would be the text that would show up in some sort of pop-up error window in an application.

HTTP/1.1 500 Server Error    @dis:Connection: close    Content-Length: 511    Content-Type: text/xml; charset=utf-8    <env:Envelope      xmlns:env="http://www.w3.org/2001/12/SOAP-envelope"      xmlns:xsd="http://www.w3.org/1999/XMLSchema"      xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"      xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/SOAP/encoding/"> <env:Body>    <env:Fault>       <env:faultcode>error271</env:faultcode>       <env:faultstring>No such ticker symbol</env:faultstring>    </env:Fault> </env:Body>

This example utilizes HTTP as the transport, but the faultcode and faultstring can be matched with any protocol.

SOAP and SMTP

The SOAP standard allows the XML in the message to bind with protocols other than HTTP. This is especially useful if you work on a project that deals with countries that do not have good connections to the Internet. Many times users in these countries, such as many on the African continent, will have the connections time out through HTTP, but with e-mail and Standard Mail Transport Protocol (SMTP) the message can take its time getting to the receiver because e-mail gets broken up into several pieces as it works its way through the Internet. HTTP, on the other hand, is looking for an immediate response within a fairly immediate timespan.

To work with SMTP, a SOAP document needs to replace the HTTP header with information needed for e-mail. Consider our Stock Quote Request again with a SMTP header.

Rather than having information needed for HTTP, such as Post and the URL of the service, the SMTP SOAP header contains an e-mail address, a subject, and a date. A SOAP request may also contain unique message Ids. This is just like sending an e-mail to a person except that software generated the e-mail to send to the receiver. In addition, instead of a text message, the application sends the SOAP document that contains the XML needed for the Stock Quote Web Service.

From: [e-mail] To: [e-mail] Subject: stock quotes Date: 18 JUN 2002 18:00:00 MDT <?xml version='1.0' ?> <env:Envelope   xmlns:env="http://www.w3.org/2001/12/SOAP-envelope"   xmlns:xsd="http://www.w3.org/1999/XMLSchema"   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"   xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/SOAP/encoding/"   xmlns:stockquote="http://advocatemedia.com/examples">   <env:Body>       <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:int[3]">         <stockquote:price          stockquote:symbol="C">53.21</stockquote:symbol>         <stockquote:price          stockquote:symbol="GE">48.00</stockquote:symbol>         <stockquote:price           stockquote:symbol="DJI">9500</stockquote:symbol>       </SOAP-ENC:Array>   </env:Body> </env:Envelope> 

The response to this request, again, contains the header for SMTP with the exact same response in the SOAP document as in previous examples. The subject should change to indicate that some sort of process actually occurred.

Note

The request and response sent via e-mail is read and created by applications of the SOAP nodes. You wouldn’t want the users of your application decoding some XML in their e-mail inbox in exchange for the data they wanted.

The message is simply returned to the sender with the appropriate XML in the body of the e-mail message.

From: [e-mail] To: [e-mail] Subject: your requested stock quotes Date: 18 JUN 2002 18:00:00 MDT <?xml version='1.0' ?> <env:Envelope   xmlns:env="http://www.w3.org/2001/12/SOAP-envelope"   xmlns:xsd="http://www.w3.org/1999/XMLSchema"   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"   xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/SOAP/encoding/"   xmlns:stockquote="http://advocatemedia.com/examples">   <env:Body>       <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:int[3]">         <stockquote:price          stockquote:symbol="C">53.21</stockquote:symbol>         <stockquote:price          stockquote:symbol="GE">48.00</stockquote:symbol>         <stockquote:price           stockquote:symbol="DJI">9500</stockquote:symbol>       </SOAP-ENC:Array>   </env:Body> </env:Envelope>

Having a choice between protocols gives a developer a great deal of flexibility of how to transmit data between nodes.