Web Service Description and Discovery Using UDDI, Part I

 

Karsten Januszewski
Microsoft Corporation

October 3, 2001

Download Atyourservice10032001.exe.

Introduction

Thus far, the At Your Service column has documented a real world scenario of how to build a Web Service, from initial design documents to business implications to final deployment. The next logical step to consider is how to publicize this Web Service so that interested clients can easily discover and consume it into their applications. A discovery mechanism that fulfills this requirement exists today: Universal Description Discovery and Integration (UDDI), an industry-wide initiative to support Web Service discovery across technologies and platforms.

The At Your Service authors have cordially offered me the opportunity to write a guest column introducing UDDI and stepping through the registration process, which I am delighted to undertake. I will first look at the implications of UDDI both from a technological and business perspective. Then I will look at the relationship between UDDI and Web Services Description Language (WSDL). Lastly, I will then step through UDDI registration and the considerations one needs to make in order to maximize the potential of UDDI. The following column, Part II, will walk through the steps that the At Your Service team performed in order to take full advantage of UDDI.

UDDI—A Global Registry of Web Services

UDDI is a public registry designed to house information about businesses and their services in a structured way. Through UDDI, one can publish and discover information about a business and its Web Services. This data can be classified using standard taxonomies so that information can be found based on categorization. Most importantly, UDDI contains information about the technical interfaces of a business's services. Through a set of SOAP-based XML API calls, one can interact with UDDI at both design time and run time to discover technical data, such that those services can be invoked and used. In this way, UDDI serves as infrastructure for a software landscape based on Web Services.

Why UDDI? What is the need for such a registry? As we look toward a software landscape of thousands—perhaps millions—of Web Services, some tough challenges emerge:

  • How are Web Services discovered?
  • How is this information categorized in a meaningful way?
  • What implications are there for localization?
  • What implications are there around proprietary technologies? How can I guarantee interoperability in the discovery mechanism?
  • How can I interact with such a discovery mechanism at run time once my application is dependent upon a Web Service?

In response to these challenges, the UDDI initiative emerged. A number of companies, including Microsoft, IBM, Sun, Oracle, Compaq, Hewlett Packard, Intel, SAP, and over three hundred other companies (see UDDI: Community for a complete list), came together to develop a specification based on open standards and non-proprietary technologies to solve these challenges. The result, initially launched in beta December 2000 and in production by May 2001, was a global business registry hosted by multiple operator nodes that users could—at no cost—both search and publish to.

With such an infrastructure for Web Services in place, data about Web Services can now be found consistently and reliably in a universal, completely vendor-neutral capacity. Precise categorical searches can be performed using extensible taxonomy systems and identification. Run-time UDDI integration can be incorporated into applications. As a result, a Web Services software environment can flourish.

How Does It Work?

The UDDI data is hosted by operator nodes, companies that have committed to running a public node that conforms to the specification governed by the UDDI.org consortium. Today, two public nodes exist that conform to the Version 1 UDDI specification: One is hosted by Microsoft and one by IBM. Hewlett Packard has committed to hosting a node under the Version 2 specification as well. Host operators are required to replicate data between one another across a secure channel, providing a redundancy to the entire UDDI cloud. Data can be published to one node and, after replication, can be discovered on another node. Today, replication occurs at 24-hour intervals; in the future, as more applications are dependent on the UDDI data, the intervals will become shorter between replication.

It is worth noting that there are no proprietary requirements as far as how a host operator implements its node. The node simply must conform to the UDDI specification. The Microsoft node (http://uddi.microsoft.com/default.aspx), for example, has been written entirely in C# and runs in production on the .NET Beta 2 Common Language Runtime. The code base takes significant advantage of the native SOAP support and serialization offered by .NET system classes. On the backend, the Microsoft operator node utilizes Microsoft® SQL Server 2000 as its data store. Suffice to say that the IBM node is using different technologies to run its node! However, the two nodes behave identically, because they conform to the same set of SOAP-based XML API calls. Client tools can interoperate with the nodes seamlessly. As such, the UDDI public cloud serves as a prime example of how the XML Web Services model works across heterogeneous environments.

Taking a look at what data is stored in UDDI and how it is structured is the next step in understanding the UDDI initiative. UDDI is relatively lightweight; it is designed as a registry, not a repository. The distinction is subtle, but crucial. A registry redirects a user to resources, whereas a repository is an actual information store. Consider the Microsoft® Windows® registry as an example: It contains basic settings and parameters, but ultimately leads an application to a resource or binary. Looking up a COM component based upon its Prog ID leads to a Class ID, which leads to the location of the binary itself.

UDDI behaves similarly: Like the Windows registry, it relies on Globally Unique IDentifiers (GUID) to guarantee the ability to perform look-ups and determine the location of resources. UDDI queries ultimately lead to an interface—a .WSDL file, .XSD file, .DTD file, and so on—or an implementation (such as an .ASMX or .ASP file) located on another server. UDDI can thus answer the following kinds of questions:

  • "What Web Service interfaces have been published that are based on WSDL and established for a given industry?"
  • "What companies have written an implementation around one of these interfaces?"
  • "What Web Services, categorized in a certain way, are offered today?"
  • "What Web Services does a given company offer?"
  • "Who do I need to contact about using a company's Web Service?"
  • "What are the implementation details of a particular Web Service?"

WSDL and UDDI

WSDL has emerged as an important piece of the Web Services protocol stack. As such, it is important to grasp how UDDI and WSDL work together and how the notion of interfaces vs. implementations is part of each protocol. Both WSDL and UDDI were designed to clearly delineate between abstract meta-data and concrete implementations, and understanding the implications of the division is essential to understanding WSDL and UDDI.

For example, WSDL makes a clear distinction between messages and ports: Messages, the required syntax and semantics of a Web Service, are always abstract, while ports, the network address where the Web Service can be invoked, are always concrete. One is not required to provide port information in a WSDL file. A WSDL can contain solely abstract interface information and not provide any concrete implementation data. Such a WSDL file is considered valid. In this way, WSDL files are decoupled from implementations.

One of the most exciting implications of this is that there can be multiple implementations of a single WSDL interface. This design allows disparate systems to write implementations of the same interface, thus guaranteeing that the systems can talk to one another. If three different companies have implemented the same WSDL file, and a piece of client software has created the proxy/stub code from that WSDL interface, then the client software can communicate with all three of those implementations with the same code base by simply changing the access point.

UDDI draws a similar distinction between abstraction and implementation with its concept of tModels. The tModel structure, short for "Technology Model", represents technical fingerprints, interfaces and abstract types of meta-data. Corollary with tModels are binding templates, which are the concrete implementation of one or more tModels. Inside a binding template, one registers the access point for a particular implementation of a tModel. Just as the schema for WSDL allows one to decouple interface and implementation, UDDI provides a similar mechanism, because tModels can be published separately from binding templates that reference them. For example, a standards body or industry group might publish the canonical interface for a particular industry, and then multiple businesses could write implementations to this interface. Accordingly, each of those businesses' implementations would refer to that same tModel. WSDL files are perfect examples of a UDDI tModel.

Registering with UDDI

Publishing to UDDI is a relatively straightforward process. The first step is to determine some basic information about how to model your company and its services in UDDI. Once that is determined, the next step is to actually perform the registration, which can be done either through a Web-based user interface or programmatically. The final step is to test your entry to insure that it was correctly registered and appears as expected in different types of searches and tools.

Step 1: Modeling Your UDDI Entry

Considering the data model outlined above, several key pieces of data need to be collected before establishing a UDDI entry.

  1. Determine the tModels (WSDL files) that your Web Service implementations use.

    Simliar to developing a COM component, your Web Service has been developed either based on an existing interface, or using an interface you designed yourself. In the case of a Web Service based on an existing WSDL, you will need to determine if that WSDL file has been registered in UDDI. If it has, you will need to note its name and tModelKey, which is the GUID generated by UDDI when that WSDL file was registered.

    On the other hand, if your Web Service is based on a WSDL file that has not been registered in UDDI, you will need to be prepared to create a new tModel to represent this interface. This tModel should have a name in the Uniform Resource Identifiers (URI) format (that is, MyCompany-com:SampleWebService-interface:v1) and should point to the location of your WSDL file.

    If your Web Service is a Microsoft® Visual Studio® .NET service, you can generate a WSDL description using a query string from the .ASMX file (that is, <http://www.mycompany.com/SampleWebService.asmx?wsdl>). However, the WSDL file generated by Visual Studio .NET is tightly coupled to the access point for invoking that Web Service, which may not be appropriate if your Web Service interface has multiple implementations. If you don't intend your WSDL file to have more than one implementation, this isn't a problem.

  2. Determine the name of your company and a brief description of the company in multiple languages, if appropriate, as well as the central contacts for your company's Web Services.

    UDDI supports the xml:lang namespace, which allows a business to provide a description of their company in multiple languages. Also, UDDI allows for contacts to be listed, including e-mail, phone, and address information. This contact list is intended to list the resources within a company that may be contacted about that company's Web Services. For instance, if someone wanted to start using your Web Service and needed to get in touch with the appropriate business relationship manager, who would that be? Is there a technical contact for using your company's Web Services? This person should be listed as well.

  3. Determine the categories and identifications appropriate to your company.

    Browse the currently supported taxonomies in UDDI from the Microsoft UDDI Node (http://uddi.microsoft.com/default.aspx). The currently supported taxonomies are North American Industry Classification System (NAICS), Universal Standard Products and Services Codes (UNSPSC), ISO 3166, Standard Industry Classification (SIC) and GeoWeb Geographic Classification. Choose which categories best represent your company.

  4. Determine the Web Services your company is providing through UDDI.

    Next, determine which Web Services your company wants to register in the public UDDI node. Are there multiple access points for this service? Are there other parameters and information necessary for clients to consume this Web Service?

    It is important to realize that registering a Web Service in UDDI does not mean that everyone has access to it. Security, authorization, and authentication can exist in tandem with a UDDI registry entry. Just because someone knows your Web Service exists doesn't mean they can actually invoke it. There very well may be out-of-band communication between the companies before granting access to a Web Service.

  5. Determine the categories appropriate to your services.

    Just as a company can be categorized, Web Services can also be categorized. As such, a company might be categorized at the business level as NAICS: Software Publisher (51121), but its hotel booking Web Service might be categorized at the service level as NAICS: Hotels and Motels (72111).

Step Two: Registering Your UDDI Entry

Upon completion of the modeling exercise, the next step is to register your company. You will need to obtain an account with a UDDI registry, which cannot be done programmatically, as a Terms of Use statement must be agreed to. The Microsoft Node uses Passport for its authentication, so you will need to have acquired a Passport (http://www.passport.com/Consumer/default.asp) in order to proceed.

There are two options at this point: You can either use the Web user interface provided by the Microsoft node, or you can register programmatically by issuing the SOAP API calls to the node itself. If you don't expect to be making many changes to your entry, or if your entry is relatively simple, using the Web user interface is sufficient. However, if you expect to be making frequent updates, or your entry is more complex, scripting the registration process using the Microsoft UDDI SDK makes sense. Also, the Microsoft User Interface is not localized for other languages, so if you want to take advantage of that feature of the UDDI API, you will need to register programmatically.

Note You can practice your registration in a sandbox environment at http://test.uddi.microsoft.com/default.aspx, which is a replica of the production node. This is a good way to become familiar with the process before moving to production.

Using Microsoft's Web User Interface

Using Microsoft's Web User Interface to register is a relatively intuitive process. Begin by navigating to the administer page. After logging in, you will be presented with the option of registering tModels and businesses. Below are a few things to be cognizant of as you proceed:

  1. Be sure to register your WSDL file as a tModel before you register the service, as the tModel will be required later in the process.

  2. When registering a WSDL document as a tModel, you should classify that tModel using the UDDI Types Taxonomy. At a minimum, your WSDL should be classified as "Specification for a Web Service" (wsdlSpec).

    Classifying it in this manner will insure that the tModel is categorized according to the "Using WSDL in a UDDI Registry" Best Practice document. Because tModels can contain references to documents other than WSDL files, it is critical to provide some classification to your tModel. Tools, such as Visual Studio .NET, rely on such classifications in order to narrow the result set of queries performed.

  3. After registering your WSDL interface as a tModel, you will need to add a business with the appropriate contact information and classification information. You may add as many classifications as you deem appropriate.

  4. Proceed with adding the Web Services you want to expose through UDDI. Because a service may have multiple implementations, you will need to add a binding for each service that you add. For each binding, you will provide the access point for the Web Service, that is, <http://www.mycompany.com/SampleWebService.asmx>.

  5. Each binding needs to create a reference to the interfaces it supports. The Microsoft UI calls these as "specification signatures." A specification signature is the tModel that contains the WSDL interface. The Microsoft UI will provide a screen that allows you to search for your tModel based on its URN. This tModel will either be the one you registered in step 1 or the tModel of a WSDL file registered by someone else.

  6. Lastly, you have the option to provide the http location of an overview document about that particular instance of your Web Service, as well as any pertinent instance parameters.

Registering Programmatically with the Microsoft UDDI .NET SDK

The other option for registration is to register programmatically. Using the Microsoft UDDI SDK makes this a trivial process. You will have to get a UDDI account using the Web UI, but upon completing that task, the rest of the process can be handled through a script. First, download and install the UDDI SDK. Then, create a new C# console application using Visual Studio .NET. Add a reference to the Microsoft UDDI SDK dll, which installs by default to C:\Program Files\Microsoft UDDI SDK\VS7\Microsoft.Uddi.Sdk.dll. Then, add some namespace references to the top of your code:

using Microsoft.Uddi;
using Microsoft.Uddi.Binding;
using Microsoft.Uddi.Business;
using Microsoft.Uddi.Service;
using Microsoft.Uddi.ServiceType;

Add the following code to static void Main (string[] args) function:

//You may want to initially run this program against the test registry at 
//https://test.uddi.microsoft.com/publish
Publish.Url = "https://uddi.microsoft.com/publish";
Publish.User = "your account here";
Publish.Password = "************";

This will establish the authentication for your account. Next, add the following code to publish your WSDL files as a tModel:

//Create tModel
SaveTModel stm = new SaveTModel();
stm.TModels.Add();
stm.TModels[0].Name = "Insert URN here";
stm.TModels[0].Descriptions.Add("en","Insert description here");
stm.TModels[0].OverviewDoc.OverviewURL = "Insert URL of WSDL here";
//The following line is necessary for proper categorization of your tModel
stm.TModels[0].CategoryBag.Add 
( "uddi-org:types",
"wsdlSpec",
"uuid:c1acf26d-9672-4404-9d70-39b756e62ab4" );

string sTModelKey = "";

//Send to UDDI
try
{
   TModelDetail tmd = stm.Send();
   sTModelKey = tmd.TModels[0].TModelKey;         
}
catch (UddiException ue)
{
   Console.WriteLine ( ue.Message );
   return;
}
catch (Exception e)
{
   Console.WriteLine ( e.Message );
   return;
}

Upon a successful save, UDDI will generate a new unique tModelKey, which you will later use in the binding of your Web Service. Next, create your business entry:

//Create Business
SaveBusiness sb = new SaveBusiness();
sb.BusinessEntities.Add();
sb.BusinessEntities[0].Name = "Insert Business Name Here";
sb.BusinessEntities[0].Descriptions.Add("en","Insert Description Here");

//Create BusinessService
sb.BusinessEntities[0].BusinessServices.Add();
sb.BusinessEntities[0].BusinessServices[0].Name = "Insert Service Name Here";
sb.BusinessEntities[0].BusinessServices[0].Descriptions.
Add("en","Insert Description of Service Here");

//Create BindingTemplate
sb.BusinessEntities[0].BusinessServices[0].BindingTemplates.Add();
sb.BusinessEntities[0].BusinessServices[0].BindingTemplates[0].
Description.Add("en","Insert Description of Binding Here");
sb.BusinessEntities[0].BusinessServices[0].BindingTemplates[0].
AccessPoint.Text = "Insert Access Point Here";
sb.BusinessEntities[0].BusinessServices[0].BindingTemplates[0].
AccessPoint.URLType = Microsoft.Uddi.Api.URLTypeEnum.Http;

//Create tModelInstanceInfo
sb.BusinessEntities[0].BusinessServices[0].BindingTemplates[0].
TModelInstanceDetail.TModelInstanceInfos.Add();
sb.BusinessEntities[0].BusinessServices[0].BindingTemplates[0].
TModelInstanceDetail.TModelInstanceInfos[0].Descriptions.
Add("en","Insert Description Here");
//Use tModelKey string from above
sb.BusinessEntities[0].BusinessServices[0].BindingTemplates[0].
TModelInstanceDetail.TModelInstanceInfos[0].TModelKey = sTModelKey;


//Send to UDDI
try
{
   BusinessDetail bd = sb.Send();
   //show xml
   Console.WriteLine ( bd );
}
catch (UddiException ue)
{
   Console.WriteLine ( ue.Message );
   return;
}
catch (Exception e)
{
   Console.WriteLine ( e.Message );
   return;
}

At this point, both your WSDL definition and business information have been saved to UDDI. By passing the appropriate key, you can always edit these entries in the future.

Step Three: Searching UDDI For Your Entry

Three checks are worth performing once your entry is registered in UDDI. First, using the Microsoft Web User Interface, search for your business based on its name and categorizations to see it returned in the result sets. Second, open Visual Studio .NET and ensure that it appears through the "Add Web Reference" dialog. If it does not appear, it is likely that your tModel was not categorized correctly using the uddi-org:types taxonomy explained above. You should be able to add the Web Service to your project and generate the proxy code based on the WSDL file. Lastly, after 24 hours, your entry will have replicated to the IBM node, which can be searched from their UI at https://www-3.ibm.com/services/uddi/protect/find.

Conclusion

UDDI and WSDL act as complimentary specifications that assist in enabling a software landscape based on Web Services. WSDL provides a vendor-neutral, formal way to define Web Services so that the next generation remote procedure calls can be realized, while UDDI provides a broad, standardized infrastructure that allows one to describe and discover Web Services. By combining these two standards, a Web Services ecosystem can flourish.

Next week's column will walk through the experience of the At Your Service team in modeling and registering the Favorites Service in UDDI.