WebReference.com - Part 3 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (4/5)

[previous] [next]

Professional XML Web Services

RPC and HTTP

We have been looking at RPC in isolation, but in order to perform a remote procedure call, we need a way to move our message to the "remote" location. Here is where SOAP really shines: when we combine RPC and HTTP to make calls against Web Services.

Assume we need to call a remote procedure on a web server to validate a city and state combination and return a zip code. Our hypothetical Web Service will exist at www.livezipcodes.com (this is not a real endpoint, don't bother trying!). We do not know how the method is implemented; all we know is how to access it. The method can be invoked at the URL https://www.livezipcodes.com/call.asp, the method is associated with the namespace URI https://www.livezipcodes.com/methods/, and the SOAPAction for this method is urn:livezipcodes. The signature for the method is shown below:

string GetZipCode ( string city, string state );

In building the request message, we do not need any extensions, so the Header element can be left out. The payload will be a struct representing the method call. The method parameters are passed as child elements. Here is the HTTP request, including the request SOAP message, sent to www.livezipcodes.com.

POST /call.asp HTTP/1.1
Content-Type: text/xml
Content-Length: ###
SOAPAction: "urn:livezipcodes"
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/"
               xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
               xmlns:xsd="https://www.w3.org/1999/XMLSchema">
   <soap:Body>
      <m:GetZipCode xmlns:m="https://www.livezipcodes.com/methods/">
         <city xsi:type="xsd:string">Modest Town</city>
         <state xsi:type="xsd:string">Virginia</state>
      </m:GetZipCode>
   </soap:Body>
</soap:Envelope>

Since there is actually a place named Modest Town, Virginia, the response from the endpoint would look like this.

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: ###
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/"
               xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
               xmlns:xsd="https://www.w3.org/1999/XMLSchema">
   <soap:Body>
      <m:GetZipCodeResponse xmlns:m="https://www.livezipcodes.com/methods/">
         <zip xsi:type="xsd:string">23412</zip>
      </m:GetZipCodeResponse>
   </soap:Body>
</soap:Envelope>

If we were to execute this same method, but the endpoint is unable to access its database of geographical information, the response would be more like this.

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml
Content-Length: ###
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/"
               xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
               xmlns:xsd="https://www.w3.org/1999/XMLSchema">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server.DatabaseDown</faultcode>
         <faultstring>The database is unavailable.</faultstring>
         <faultactor>https://www.livezipcodes.com/call.asp</faultactor>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Beyond RPC - Working with XML Documents

Although RPC has certainly received the most attention, SOAP messages can be used to transfer arbitrary XML documents. For a given document type, we can define a new convention that describes the purpose of the message transfer.

Here's something we don't see everyday: a SOAP message that has nothing to do with RPC.

<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/"
               xmlns:xsl="https://www.w3.org/1999/XSL/Transform">
   <soap:Body>
      <xsl:stylesheet version="1.0">
         <xsl:template match="/">
            <html>
               <body>
                  <p><xsl:value-of select="Envelope"/></p>
               </body>
            </html>
         </xsl:template>
      </xsl:stylesheet>
   </soap:Body>
</soap:Envelope>

This message contains a payload that is an XSLT stylesheet (one that happens to be written to manipulate a SOAP message). Consider the implications of having the SOAP Body element be an arbitrary XML document (in this case, an XSLT stylesheet) instead of RPC. In that sense, SOAP is a general-purpose mechanism for transporting an XML document. This is how SOAP is being applied in both Microsoft's BizTalk Server and in the ebXML protocol, but the potential uses do not stop there.

For more information on BizTalk, go to the BizTalk Home Page at https://www.biztalk.org/home/default.asp. Additional information about ebXML is provided in Chapter 1 of this book, and https://www.ebxml.org/

For every potential application of XML, SOAP provides the mechanism for extending that use via messaging. This is an area of development that is still largely untapped because of the excitement surrounding RPC. Web Services can be composed with SOAP but without RPC. As more developers realize this, the excitement surrounding SOAP will continue to grow. Inserting an XSLT transform into a SOAP message gives us a mechanism to trigger an XML transformation on a remote machine, and that's a Web Service. A SOAP message that carries a Vector Markup Language (VML) document could be used to insert new graphical elements into a diagram that exists on another machine, and that's a Web Service too. The possibilities are endless!

[previous] [next]

Created: November 26, 2001
Revised: November 26, 2001

URL: https://webreference.com/authoring/languages/xml/webservices/chap3/3/4.html