Gaining a Web Services Vocabulary

Web services exchange messages between a consumer (client or sender) and provider (server or receiver). The provider and consumer are called endpoints. The consumer initiates the exchange with an XML request document; the provider ordinarily returns an XML response document that contains the requested information. If the request message is malformed or the provider can't supply the requested information, a fault occurs.

Like other Web-related technologies, Web services are, by definition, loosely coupled. Loosely coupled means that Web services don't rely on a permanent connection between the consumer and provider. Providers listen for incoming SOAP request messages and respond in ad hoc fashion. Windows XP/2000+ use Internet Information Server (IIS) 5.0+ and an Internet Services Application Programming Interface (ISAPI) filter to listen for incoming request messages and route the messages to the appropriate service. Thus, you can set up your own public or private services that run on Windows XP or 2000 Professional, as well as Windows 2000+ server.

Web Service Standards and Specifications

Much of the vocabulary of Web services is defined in the following three standards that apply to Web services and the messages they exchange:

• SOAP (originally Simple Object Access Protocol) is the basic specification that covers the structure of XML request and response messages. SOAP 1.1, the version in common use when this book was published, isn't a W3C recommendation; it's a W3C note that's been adopted as a de facto industry standard. The SOAP 1.2 recommendation consists of three parts Part 0: Primer (http://www.w3.org/TR/soap12-part0/) is a SOAP tutorial; Part 1: Messaging Framework (http://www.w3.org/TR/soap12-part1/) is the basic SOAP 1.2 specification; and Part 2: Adjuncts (http://www.w3.org/TR/soap12-part2/) provides recommendations for SOAP 1.2 implementations.

• Web Services Description Language (WSDL, pronounced "wizdle") is the specification for an XML document that defines the structure and content of SOAP request and response documents for a particular Web service. A WSDL document serves as a contract between the provider and consumer. If the consumer submits a request message that conforms to the WSDL document's requirements, the provider agrees to respond in a WSDL-defined fashion. Office 2003's WSR and Visual Studio .NET's Add Web Reference feature automatically generate custom classes from WSDL documents. Like SOAP 1.1, WSDL 1.1 is a W3C note; the current W3C specification for WSDL 1.2 is at http://www.w3.org/TR/wsdl12/.

  Note

  The term WSDL document includes static WSDL files (ServiceName.wsdl) and the dynamic WSDL documents generated by Microsoft's ASP.NET Web services.

  
  

• Universal Description, Discovery, and Integration (UDDI) specifications define methods for locating endpoints and WSDL documents for Web services on private intranets or the Internet. IBM, Microsoft, and SAP are operators of public UDDI Business Registries (UBRs) where providers can advertise their Web services. Potential consumers can search the UBRs by provider name, service name, or industrial and geographical classifications. UBRs replicate registrations frequently, so each UBR delivers identical information. WSR2 defaults to the Microsoft UBR for Web service discovery. OASIS maintains the UDDI 2.0 and 3.0 standards. You can learn more about UBRs at http://www.uddi.org/faqs.html. Windows Server 2003 includes a private UDDI 2.0 registry for deployment on intranets.

Fortunately, you don't need a thorough understanding of the Web services standards and specifications to consume or provide them. WSR automates VBA code generation for Access 2003 Web service consumers. The Microsoft SOAP Toolkit 3.0+ installs an ISAPI SOAP listener for IIS 5.0+ to enable providing Web services. This Toolkit also creates SOAP 1.1 wrappers and generates WSDL files for Visual Basic 6.0 ActiveX components automatically.

SOAP Message Formats

SOAP messages consist of an envelope that contains a body and optional header elements. The body contains the request or response message. Header elements typically provide message routing and security-related information for advanced Web services. Most public Web services don't include header elements; if they do, processing the header usually is optional. WSR2 can't handle mandatory headers, so this chapter's examples don't include them.

Following is an example of a simplified SOAP 1.1 request message to ZipCodeResolver, a public address-correction Web service provided by EraServer.NET:

 <?xml version="1.0" encoding="utf-8"?> <soap:Envelope   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   xmlns:xsd="http://www.w3.org/2001/XMLSchema">   <soap:Body>    <CorrectedAddressXml       xmlns="http://webservices.eraserver.net/">      <accessCode>9999</accessCode>      <address>1000 Broadway</address>      <city>Oakland</city>      <state>CA</state>     </CorrectedAddressXml>    </soap:Body> <soap:Envelope> 

The request message invokes a CorrectedAddressXml function (called a Web service method or Web method) that returns the address in standard US Postal Service format with five-digit and ZIP+4 ZIP codes. The Web method sends an HTTP GET request with the address, city, and state to the USPS Web site, which delivers a page that contains the corrected address in an HTML table. The service extracts the required data from the page to a public class (user-defined type) named USPSAddress, which has Street, City, State, ShortZIP and FullZIP members. The process of extracting specific pieces of data from Web pages is known as screen scraping. Transforming an instance of a class to an XML document fragment is called serialization; the reverse is deserialization.

Following is the CorrectedAddressXML method's SOAP 1.1 response message:

 <?xml version="1.0" encoding="utf-8"?> <soap:Envelope   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   xmlns:xsd="http://www.w3.org/2001/XMLSchema">  <soap:Body>   <CorrectedAddressXmlResponse     xmlns="http://webservices.eraserver.net/">    <CorrectedAddressXmlResult>     <Street>1200 BROADWAY</Street>     <City>OAKLAND</City>     <State>CA</State>     <ShortZIP>94612</ShortZIP>     <FullZIP>94612-1802</FullZIP>    </CorrectedAddressXmlResult>   </CorrectedAddressXmlResponse>  </soap:Body> </soap:Envelope> 

A WSDL document defines the format of the SOAP request and response messages, and specifies the Web service's URL. There are two widely used Web service message formats rpc/encoded and document/literal. The first element (rpc or document) specifies the SOAP body's use and the second determines the message style. You determine the format of the request and response messages by inspecting the <operation> node(s) of the WSDL document, as illustrated by the following excerpt for the document/literal CorrectedAddressXml method:

 <operation name="CorrectedAddressXml">  <soap:operation    soapAction="http://webservices.eraserver.net/CorrectedAddressXml"    style="document"  />  <input>   <soap:body use="literal" />  </input>  <output>   <soap:body use="literal" />  </output> </operation> 

The WSDL document for ZipCodeResolver is 20KB in size and far too large to be reproduced here. Typical request and response messages, and ZipCodeResolver.wsdl are located in the \Seua11\Chaptr31\ZipCodeResolver folder of the accompanying CD-ROM.

Most early Web services employed the rpc/encoded format, which emulates a remote procedure call by encoding specific message data types in accordance with section 5 "SOAP Encoding" of the SOAP 1.1 specification. It turned out to be very difficult to assure service interoperability with the rpc/encoded format, so WS-I's Basic Profile 1.0 specification precludes its use by requiring literal as the value of the use attribute. The literal value requires that message data types conform to the W3C's XML Schema Part 2: Datatypes recommendation.

The Basic Profile 1.0 permits two message formats document/literal and rpc/literal. The document/literal format is much more popular; only a few SOAP toolkits support rpc/literal messages. WSDL files for document/literal often abbreviated doc/lit services define the messages, not just datatypes, by XML schemas (XSD). All but one of this chapter's examples are document/literal.