Finding and Describing Web Services | Professional ASP.NET MVC 1.0 (Wrox Programmer to Programmer)

If you're building an application and decide that you'd like to use a web service to provide certain functionality, how do you find a web service that meets your needs? Just as you would use a tool such as Google to find web pages, use a similar directory-oriented tool to find web services: it's called Universal Description, Discovery, and Integration ( UDDI ). UDDI is a well-known location to find and register web services.

Universal Description, Discovery, and Integration

Microsoft, IBM, and Ariba jointly announced UDDI in September 2000. UDDI is a project that strives to define how businesses describe and publish web services and consists of two main elements:

UDDI XML schema for business description :This schema is used to define XML documents that describe various elements of a business; for example, contact information, business categorization, and web services offered . When you search UDDI for a service, you are searching against XML documents that conform to this schema.
Web-based registry :The business description data is available either through a standard browser interface, or through published, SOAP-based Web services. You can use the web services to interact programmatically with the UDDI schema repository.

Note
Further details about UDDI can be found at http://www.uddi.org, along with the public specifications.

In a manner similar to a phone book, you can use the UDDI web services directory as the yellow, white, and green pages to find web services offered by organizations. For example, a company that provides a credit card web service can register the service at http://UDDI.org. Then, customers who need a credit card web service can visit http://UDDI.org and query the registry for the existence of suitable credit card services through UDDI's public SOAP-based Web services or through their browser. If services matching the criteria of the request are found, the company will have the necessary information (the location and description of the web service) to access them.

UDDI Implementations

UDDI allows organizations to register and discover web services that other organizations have registered. The specification at the time of writing is implemented by Microsoft at http://uddi.microsoft.com/ and by IBM at http://www-3.ibm.com/services/uddi/.

UDDI nodes mirror each other. If one node is unavailable, another node can be used, thus eliminating single points of failure. In the future, additional UDDI nodes should become available. It's also possible that private UDDI servers will be made available. This would allow organizations to host their own intranet UDDI nodes for intra-organizational web service registration and discovery.

We won't look at how to use UDDI programmatically, but will discuss the steps involved in finding web services using a browser at one of the existing UDDI nodes. We'll look at Microsoft's UDDI node, available at http://uddi.microsoft.com.

Microsoft UDDI Node

When you navigate to http://uddi.microsoft.com, you're served a simple HTML page that contains news and information about the UDDI project. You can search this node for services, after logging in through Passport.

Searching the Microsoft UDDI Node

The Search link brings up another web page that details how you can search for services. An HTML form is provided for entering the search parameters. Since we're looking for web services offered by Microsoft, we can search for the value Microsoft from the Providers tab. Other search options include:

Option	Searches by	Example
Business location	Location of the business.	Redmond
tModel name	Services that support a certain type of service.	SOAP
Business identifier	A D-U-N-S reference number for business lookup.	08-146-6849 for Microsoft
Discovery URL	The location of the service. You can check if a known service is registered with UDDI.	A URL for a service that we already know exists: reverse lookup
GeoWeb Taxonomy	By geographic classification.	North America
NAICS Codes	North American Industry Classification.	Software Publisher
SIC Codes	Standard Industrial Classification.	Classification code used to classify business types
UNSPSC Codes	Universal Standard Products and Services Codes.	Software

After querying UDDI, you are presented with the results. In our case, the Results present a link to a page that describes the registered services for Microsoft. Follow this link.

Details Tab

The Details tab lists details entered by the web service owner, such as a unique provider key as well as a name and description of the service.

Bindings Tab

The Binding tab lists any web service end-points. Using the information provided in the bindings, you can use the technologies found in .NET to easily build proxy classes that can use these SOAP-based web services.

Note	UDDI allows you to search a common repository for published web services. If you find a web service that meets your needs, you can then access that web service using the binding details provided by UDDI.

UDDI solves the problem of web service discovery. However, even after you've found the web service, some issues need to be addressed:

How to describe what the web service can, and can't, do
What does the SOAP request look like
What does the SOAP response look like
What data types does the web service support
Does the web service require an XML schema

While UDDI makes finding web services easy, Web Service Description Language ( WSDL ) is used to describe the capabilities of a web service and it is WSDL that answers these questions.

Web Service Description Language

WSDL is a W3C submitted specification (at the time of writing it is not yet a W3C standard) supported by a number of industry leaders , including Microsoft and IBM.

Note	The public specification, available at http://msdn.microsoft.com/xml/general/wsdl.asp, states, "Web Service Description Language is an XML format for describing network services as a set of end-points operating on messages containing either document-oriented or procedure-oriented information."

WSDL is an XML document that describes:

How a web service is used :For example, how both the client and the server send and receive messages
The location of a web service :For example, the URI to which messages are sent, in order to interact with the web service

The nature of the message exchange :SOAP allows for either an XML document or XML RPC view of messages.

Note	If you come from an object development background and have used Interface Definition Language (IDL) to describe an object, its methods , and the interfaces it supports, you'll find that WSDL is similar in concept but uses XML and describes a web service rather than a component.

Interoperability between Web Services

Web services are interoperable at network level. The implementation of a web service is completely independent of the operating system or the technology used to implement the service, and the description of the web service is encapsulated in an XML document (WSDL).

For example, if JSP developers wanted to use ASP.NET Web services in their application, they would simply need to examine the WSDL for the web service and format the correct message to a named end-point. The return message could then also be interpreted (again using WSDL) and the appropriate value extracted. However, it doesn't need to be this complicated. With .NET, using web services requires a trivial amount of work.

WSDL is an incredibly important technology for enabling web service interoperability because it fully describes the capabilities and use of the service. In fact, the description is so complete that tools can use WSDL to automate the creation of code. Let's look at a sample WSDL document that describes the Fibonacci Web service implemented in the previous chapter.

Using WSDL with the Fibonacci Web Service

Recall from the previous chapter that an ASP.NET Web service provides a Web Service Description help page that allows you to interact and test the web service through a browser.

The help page provides a link called Service Description. This requests the current document, and appends ?WSDL to the request URL. Selecting the Service Description link provides us with WSDL. The WSDL document that describes the Fibonacci ASP.NET Web service follows . We implemented the web service in both C# and VB.NET, but this is completely abstracted by the WSDL.

Sections of the WSDL that describe the use of the HTTP-GET and HTTP-POST protocols have been removed in this example (to decrease the size ). This WSDL document only describes web services using SOAP:

 <?xml version="1.0" encoding="utf-8"?> <definitions xmlns:s="http://www.w3.org/2001/XMLSchema"              xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"              xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"              xmlns:urt="http://microsoft.com/urt/wsdl/text/"              xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"              xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"              xmlns:s0="http://tempuri.org/"              targetNamespace="http://tempuri.org/"              xmlns="http://schemas.xmlsoap.org/wsdl/">    <types>       <s:schema attributeFormDefault="qualified"                 elementFormDefault="qualified"                 targetNamespace="http://tempuri.org/">          <s:element name="GetSeqNumber">             <s:complexType>                <s:sequence>                   <s:element minOccurs="1"                      maxOccurs="1"                      name="fibIndex"                      type="s:int" />                </s:sequence>             </s:complexType>          </s:element>          <s:element name="GetSeqNumberResponse">             <s:complexType>                <s:sequence>                   <s:element minOccurs="1"                      maxOccurs="1"                      name="GetSeqNumberResult"                      type="s:int" />                </s:sequence>             </s:complexType>          </s:element>          <s:element name="int" type="s:int" />       </s:schema>    </types>    <message name="GetSeqNumberSoapIn">       <part name="parameters" element="s0:GetSeqNumber" />    </message>    <message name="GetSeqNumberSoapOut">       <part name="parameters" element="s0:GetSeqNumberResponse" />    </message>    <portType name="FibonacciSoap">       <operation name="GetSeqNumber">          <input message="s0:GetSeqNumberSoapIn" />          <output message="s0:GetSeqNumberSoapOut" />       </operation>    </portType>    <binding name="FibonacciSoap" type="s0:FibonacciSoap">       <soap:binding          transport="http://schemas.xmlsoap.org/soap/http" style="document" />       <operation name="GetSeqNumber">          <soap:operation                soapAction="http://tempuri.org/GetSeqNumber" style="document" />          <input>             <soap:body use="literal" />          </input>          <output>             <soap:body use="literal" />          </output>       </operation>    </binding>    <service name="Fibonacci">       <port name="FibonacciSoap" binding="s0:FibonacciSoap">          <soap:address location="http:// ... /Fibonacci_cs.asmx" />       </port>    </service> </definitions>

This WSDL document is divided into five major sections:

<Types> : This section of the WSDL is simply an XML schema used by the web service to define the schema for the message sections. The XML schema defines a set of rules for how XML data should be formatted. The resulting XML can be validated against the schema.
<message> : For each web service described in the WSDL, there will be at least one <message> element. There may be only one as a web service can be one-way (read-only) as well as two-way (request/response). In our example, the GetSeqNumber Web service is two-way, and so we have both a request message ( GetSeqNumberSoapIn ) and a response message ( GetSeqNumberSoapOut ).

The <message> element describes the format that the web service expects to receive the request in, as well as the format the web service will use when it responds. Both the examples in this WSDL support parameters and use an XSD (XML Schema) to describe the message format defined in the <types> element.
<portType> : The WSDL may describe multiple web services. The <portType> element is used to describe the request and response messages (defined by <message> elements) that these web services support. In this example, the only web service described is GetSeqNumber . This is the value of the name attribute of the <operation> element in the <portType> element. If we exposed additional web methods, we would expect to find a definition for them as well. Within the <operation> tag, we then find the <input> and <output> elements, which reference <message> elements within the WSDL.
<binding> : This element describes the message format, as either SOAP section 5 RPC-style encoding, or XML document-style encoding. Each method supported by the web service can vary in its support of message encoding and thus each web service described by the WSDL receives its own section within <binding> . The only web service described in this WSDL is GetSeqNumber .
<service> : The name of the web service is defined in the <service> element's name attribute. Also defined in the <service> element is the <port> element, which identifies the location of the web service (that is, the end-point that the service calls) as well as any bindings that the web service uses. The values in the <port> element are further described by the <binding> and <portType> elements. By default, the service name corresponds to the classname of the ASP.NET Web service we authored but is configurable using the WebService attribute on the web service.

XML namespaces are used extensively in WSDL and we'll discuss them next .

Applying Namespaces to WSDL

XML uses namespaces to uniquely identify sections of an XML document. Namespaces are Universal Resource Indicators ( URIs ) such as http://microsoft.com and allow the markup language used to be unique within a given namespace.

Note	Even though a URI might take the shape of an http:// address, this does not imply that some value or meaning exists at this end-point, it is simply a unique string.

Software can use namespaces to differentiate between a <GetSeqNumber> element from Microsoft and a <GetSeqNumber> element from a third party. The default namespace ASP.NET assigns to web services is http://tempuri.org, as is evident in the previous WSDL (you saw in the previous chapter how to use the Namespace property of the WebService attribute to change the default namespace).

The WSDL generated by ASP.NET describes three protocols: SOAP, HTTP-POST, and HTTP-GET (all described in the previous chapter). You don't actually need a thorough understanding of WSDL to build web services. With ASP.NET the WSDL is created automatically.

We've had a foundation in UDDI and WSDL; let's shift our discussion towards using WSDL to build a proxy class capable of calling a web service.