How to find Web services: the UDDI registry.

After a Web service is set up, people must have a way to find and use the service. That's the purpose of the universal description, discovery, and integration (UDDI) registry, established by an industry consortium to create and to implement a directory of Web services. The UDDI registry accepts information describing a business, including the Web services it offers, and allows interested parties to perform online searches and downloads of the information.

To contact a business to order something, you need a way to find information about that business: street address, telephone number, Web site, or Web service address. You can obtain the address and other information directly from a business representative, perhaps in the form of a business card, handwritten note, or e-mail. You can also look up a business name in a telephone directory and obtain the address and telephone number.

Similarly, the information necessary for a program running on your computer to talk to a program running on someone else's computer over the Web must be published. Although UDDI is like a White Pages or Yellow Pages for Web services, it also enables developers to interact with UDDI at both design time and runtime. In short, UDDI resources can be considered part of the Web services architecture and infrastructure.

When you want to interact with a business's Web service to check inventory availability before placing an order or to check for the right hotel, car, and flight before making a travel reservation, you need to be able to find and contact the business's Web service.

If you don't know the business name or if you want to compare several suppliers' terms and conditions, the problem becomes greater, and the need for a generic search and discovery mechanism becomes more evident. The UDDI registry provides such a mechanism and is therefore important to the ultimate success of Web services. Figure 1 illustrates the public UDDI service hosted by IBM, Microsoft, SAP, HP, and potentially others. Each vendor provides a publicly accessible database containing business registry data, posted via SOAP requests to one of the vendor's data centers and replicated to the others. SOAP requests query the results of the posted updates to find information about businesses to be contacted, including metadata about a business's Web services.

The hosted databases are called operator sites, and UDDI programmers use SOAP APIs to interact with one or more of the sites. (API- Application Programming Interface) The operators do not charge for the basic UDDI service. Business data can contain pointers to Web services interface specifications, such as WSDL. Private UDDI services are often used to store a business's internal information, such as a list of available Web services.

The UDDI Organization

UDDI began as collaboration among Microsoft, IBM, and Ariba to promote the adoption and use of Web services standards.

The companies founded UDDI.org and invited other companies to participate: some with founders' rights and others with advisory privileges. The companies invited as founders set the ground rules, defined the initial specifications and requirements, and decided on the eventual disposition of the work.

The three original founders were also the original operators, or hosts, of the initial public UDDI repository. Later, Hewlett- Packard joined the project and replaced Ariba as a registry host.

SAP joined as another operator. Other operators may join over time if they meet the terms and conditions set by the original operators and if the founding membership agrees. More than 300 companies joined UDDI.org in support of the effort to establish a Web-hosted business directory of services. Fifteen of the companies form the core Working Group that is responsible for setting the strategic course of the project and for resolving conflicts and making decisions. The remainder are members of the Advisory Group, which allows a company to review and to comment on specification drafts before they're made public and, on approval or invitation of one or more of the Working Group members, to join one of the specification drafting teams. The Working Group members have the final say on organizational issues and specification decisions, but small teams, including companies not in the core membership, perform the work on specifications. The specifications developed by theteams are sent for review and approval to the entire membership before they are published. UDDI v2, on which this is based, contains enhancements, such as publishing the operator and replication specifications, improving the query capability, and providing internationalization support.

UDD1.org announced its intention to complete v3 of the specifications and to submit them to a standards body, perhaps W3C or OASIS, for further maintenance and enhancement.

The founding members did not submit the work to a standards body originally, because it's more efficient and effective to develop the specifications in a private consortium first; more progress could be made more quickly that way, they said.

Also, UDDI is unique as a specifications development group in as much as part of the core membership also hosts the public service based on the specifications.

The operators run both a test site and a production site, allowing Web services providers and businesses to test their UDDI clients before posting real information to the production database. Of course, before being allowed to post the real information to the production database, a business needs to be authorized to do so, and the data needs to be validated. To prevent spoofing and wiretapping, communication with UDDI requires encrypted messages in the form of HTTPS. Among the work items for UDDI 3 is improved security.

The Concepts Underlying UDDI

The public UDDI registry works a little like the Internet domain name service (DNS). Businesses can register with any of the hosts-4BM, HP, SAP, or Microsoft-and the information they provide will be placed into the database at that host site. At regular intervals, at least nightly, all information placed into one of the host site databases is replicated to the other host site databases, ensuring that they are all kept in synch. Users requesting data about a business can then receive the same information about a registered business from any of the host databases. When it needs to update the data, however, a business must return to the original site to which the data was placed and execute the update function.

For obvious reasons, security is a primary concern of UDDI.org members. Businesses are authorized to update information by one of the operators and therefore must return to the original operator to change or to delete any information they posted. Businesses wishing to register with UDDI must first obtain authorization to do so and must be approved by at least one of the operators. Approval means sending to the business an authorization token that allows the business to log onto the UDDI site and to store or to update data. Authorization to update the registry is handled by the operators individually; login information from one operator will not work for another. For all practical purposes, someone registering information with UDDI has to choose one of the operators and stick with that operator.

Another primary concern is the quality, or validity, of the data. Someone has to ensure that the business being registered is a real business; that the business name, ID number, category information, phone number, Web page, and street address are correct; and that the business category and geographical information are correct. UDDI v2 is set up to allow third parties to do this and does validate category data.

UDDI has two main parts: registration and discovery. The registration part means that businesses can post information to UDDI that other businesses can search for and discover, which is the other part. Businesses and individuals interact with UDDI by using SOAP APIs or one of the user interfaces provided by the operators or other Web services vendors. UDDI operators post WSDL descriptions of their Web services for registration and discovery. UDDI provides separate WSDL files for registration and discovery services, using its own XML document format.

Some UDDI SOAP APIs are used for inserting information the registry; others, for browsing and retrieving specific information from the registry. UDDI APIs require a specific subset of SOAP; that is, UDDI does not use the optional serialization format and some other features defined in the SOAP specification.

How UDDI Works

UDDI information is often described as being divided into three main categories of business information:

* White Pages: Business name and address, contact information, Web site name, and Data Universal Numbering System (DUNS) or other identifying number.

* Yellow Pages: Type of business, location, and products, including various categorization taxonomies for geographical location, industry type, business ID, and so on.

* Green Pages: Technical information about business services, such as how to interact with them, business process definitions, and so on. A pointer to the business's WSDL file, if any, would be placed here. Information in this category describes a service's features/functionality, including a unique ID for the service. This category is quite new and specific to the Internet.

The data structure of UDDI is expressed using complex types in XML schemas. These schemas allow for extensibility and great flexibility in the data stored for a particular business or entity. Classification and identification information is useful for searching and retrieving lists and specific details about businesses.

Businesses can add any number of classifications to their registration.

Classification taxonomies for category information include the following:

* North American Industry Classification System (NAICS)-www.census.gov/epcd/www/naics.html

* Universal Standard Products and Services Classification (UNSPSC)-www.unspsc.org

* International Organization for Standardization (ISO) 3166-www.din.de/gremien/nas/nabd/iso3166ma (geographical regions, codes for countries, and so on)

Operator sites validate category information for industry codes via NAICS, product and service classifications via UNSPSC, and geographical codes via ISO 3166. However, including information on any or all of these categories is optional, as is checking this data when registering. Other classification taxonomies can be used, but they are not checked for validity.

UDDI v2 supports checked and unchecked classifications and identifications. Although UDDI does not check or validate classification and identification information beyond NAICS, UNSPSC, and ISO 3166, UDDI.org does support a program that is meant to encourage third parties to provide such an ancillary service.

UDDI Data Model

UDDI registration information is comprised of the following five data structure types:

* businessEntity, the top-level structure, describing the business or other entity for which information is being registered. The other structures are related via references from this structure.

* businessService, the name and description of the service being published.

* bindingTemplate, information about the service, including an entry-point address for accessing the service.

* tModel, a fingerprint, or collection of information uniquely identifying the service specification. This data structure also supports top-level searches.

* publisherAssertion, a relationship structure putting into association two or more businessEntity structures according to a specific type of relationship, such as subsidiary or department of.

When the data is submitted for the first time, the UDDI operator assigns a unique key that identifies each of these data structures. The unique keys take the form of universally unique identifiers (UUIDs), sometimes called globally unique identifiers (GUIDs). The UUID format is derived from the Open Software Foundation (now part of the Open Group) Distributed Computing Environment; formalized now as ISO/IEC 11578: 1996 Information Technology-Open Systems Interconnection-Remote Procedure Call (see also wwwiso.ch/ cate/d2229.html)

A UUID generator uses a complex algorithm, which takes into account factors, such as the current date and time, to produce a hexadecimal number that has a statistical guarantee of uniqueness. The odds of producing a duplicate number, in other words, are so great as to be impossible in practice. An example of a UUID is C90D73ID-777D-4130-9DE3-5303371170C2.

Figure 2 illustrates the basic UDDI data model, in which data related to the businessEntity structure can be retumed as results to a query. Relationships among data structures are established via key references.

In Figure 2, the underlined fields, such as businessKey, are required elements; that is, a request to store data will be rejected if these elements are not present, although in some cases a required element can contain zero entries. The data model is a containment hierarchy in which businessEntity is the root, or top-level, structure. The publisherAssertion schema was added for UDDI v2 to allow multiple businessEntity entries to be placed in relation with one another-for example, to accommodate large companies wishing to register their various divisions or subsidiaries.

The arrows in Figure 2 illustrate the elements that are used to establish the relationships. The entry in businessServices in the businessEntity Schema is optional; if present, it contains one or more serviceKey fields containing key values that are present in associated businessService entries.

Similarly, the bindingTemplate element in the structure businessService contains bindingKey entries that reference any associated bindingTemplate structures. The bindingTemplate in turn references the tModel structure. Information in the bindingTemplate and the tModel structures can be combined to find a complete Web service interface.

Generic Data

UDDI is designed to accept virtually any type of Web services description, including industry-specific description languages. WSDL provides a general-purpose language for describing the interface, protocol bindings, and deployment details and as such is complementary to UDDI but not required by it In other words, the data structures established by UDDI not only predate WSDL but also are designed to be completely extensible to contain and to reference any type of contract agreement between two parties in a distributed or networked exchange of information.

The XML schema structures defined for UDDI do not prescribe any underlying storage format. That is, the way in which the data is sent to a UDDI operator may be different from the way in which it is stored. This doesn't matter as long as the XML structure can be recreated from the persistent database storage format. (This is consistent with the whole XML approach to data independence, which relies on mapping into and out of XML structures that are independent from the way in which data is represented in the underlying programs and databases.)

As shown in Figure 3, the UDDI data structures provide several types of information, including contact, identification, and category, to be stored in association with the main businessEntity structure. Each of these is handled via repeating types of information sequences contained within the businessEntity structure. The descriptive information is basically the information that can be searched for a match and for which service information can be returned via reference to the tModel keys.

The Business Entity

The top-level structure (businessentity) is where most queries start. Depending on the type of information being searched, however the queries will usually also include one or more identifiers or category keys. Queries may also start with other entities, however. Here is an example. (Fig 4)

Figure 4 illustrates the XML definition for the top-level businessEntity structure. The schema defines a complex element sequence constrained by the use of attribute names and usage qualifiers for repetition and required characteristics.

BusinessKey is required, and UUID keys are assigned when the structures are created. The minimum necessary to create a businesskey entity, therefore, is the business name, and queries typically start with that.

The Binding Template

The binding template provides information for physically accessing a Web service or other type of service registered with UDDI. A business may register multiple binding templates for a given business service and identify different access points for that service, if appropriate or useful. The access point types in the binding Template structure include the following URL types:

* mailto:

* http:

* https:

* ftp:

* fax:

* phone:

* other:

The information following the type has to be formatted correctly for the type. For example, the mailto: type requires a valid e-mail address; the http: type, a valid URL format; and phone: a valid telephone number. In this way, a business can provide the right access type for various contact mechanisms for the same or different services. No validation is done to ensure that something exists at the other end of the address; in most cases, however, this is no more of a concern than the general concern over the validity of UDDI data.

The tModel

In UDDI terms, a tModel is the mechanism used to exchange metadata about a Web service, such as the Web service description, or a pointer to a WSDL file. The UDDI definition of a Web service is much broader than the examples shown in this feature. The UDDI registry aims to be general enough to support any type of service accessible over the Internet. So that's why UDDI doesn't use only WSDL. If WSDL becomes popular and widely accepted, perhaps most tModels will use WSDL. For now, however, other protocols can be considered Web services by UDDI's definition, at least in terms of what's acceptable to put in a tModel.

UDDI also predates WSDL. In this feature WSDL has been used as an integral part of a Web services definition, but UDDI de fines a Web service a bit differently and more broadly. UDDI defines Web services as "technical services that are exposed for either private or general use. Examples include purchasing services, catalog services, search services, and shipping or postal services exposed over transports, such as HTTP or electronic mail.' Business-to-business protocols, such as RosettaNet and ebXML, can be considered Web services by UDDI's definition, although neither of them uses WSDL.

A tModel is roughly the UDDI equivalent of WSDL but is broader and can include pointers and references to services using addresses other than URLs and transports other than SOAP. Each tModel is assigned a UUID key by an operator when initially stored. The descriptive information stored in association with the main tModel structure is intended to help ensure that duplicate services can be identified. A tModel is designed to identify uniquely interface specifications for Web services-in the broad sense in which UDDI defines them-and to help allow them to be discoverable. A tmodel provides alternative entry points into the UDDI data structures in order to discover specific services and to link them to the businesses that provide them. It's also likely that multiple businesses will end up exposing the same service. Once firmly established, Web services are not going to be unique or customized to a particular business.

The tModels, representing keyed metadata about a service, are intended to ensure compatibility of interfaces or services across multiple registry entries. To be useful, a tModel should contain a pointer to a place where the user can obtain more information about the service.

Another intended function of tModels is to support registry searches for a specific service. For example, suppose that your business wants to access a catalog service or a credit card validation service. The UDDI APIs support searching for specific service definitions and listing the companies that offer compatible services. If you can obtain a tModel key value associated with the specific type of service you want, you can search UDDI for companies that offer it. A tModel is intended to be a separate, independent entity referenceable by one or more businesses that offer a given Web service. In other words, the UDDI designers assumed that a Web service might be a generic or general-purpose service that more than one business or entity would provide. Therefore the tModel is not specific to a given business or entity and is a searchable structure in its own right, linked to one or more businesses or entities.

The reverse is also true; a business or an entity can reference multiple tModels. In the short term, it seems likely that most businesses will expose unique Web services, but over time, it seems likely that some companies will host services for other companies, and perhaps multiple companies will get involved in the Web services hosting business.

UDDI defines tModels to look up its own services, including tModels that define the inquiry and publisher APIs for interacting with the registry and taxonomy maintenance APIs. For example, tModels are defined for NAICS, UNSPSC, and ISO 3166 classification taxonomies. These examples illustrate the use of a tModel as an abstract namespace definition.

UDDI SOAP APIs

The UDDI APIs are divided into those that register information and those that search the information in the registry. The registration APIs are used by publishers, that is, by businesses and/or business agents that send requests to enter the information into UDDI. The search ARIs are used by registry to find business information by category and to retrieve detailed information about one or more individual businesses that meet the search criteria.

In general, APIs for registering information include saving and updating current information and deleting old information. APIS for searching information include returning summary information about a group of entries or returning complete information for a specific single entry.

Anyone wishing to use any of the publisher APIs must first apply for an authentication token from an operator. Each operator distributes authentication tokens using its own mechanism; so in practice, a publisher interacts with only one operator. A publisher therefore signs up with an individual operator and is granted credentials for logging on and using the publisher APIS. The publisher APIs are required to be used over HTTPS (SSL v3.0) for encryption on the wire.

Versioning is accomplished via namespaces. For example, the following is an attribute on the v2 APIs to indicate that the v2 APIs are being used:

xmlns="urn:uddi-org:api_v2"

Publisher and consumer SOAP APIs are available via HTTP POST only. APIs support Unicode, which requires the use of UTF-8 encoding. Publishers can register business and other descriptions using multiple human languages.

Inquiry APIs

Using one or more search criteria, the inquiry APis browse registry information and obtain specific information about a registered business or service specification once the proper unique key is obtained.

Various search criteria are used to find one or more matching records. Typically, a search starts with a generic request that returns a list of businesses that match a given category or identification string. Then other inquiry APIs are used to return service and/or contact information for a given specific business. Inquiries can be done using matches on business names or identifiers or using category information, such as industry type or geographic location. Inquiry APIs are as follows:

* find_binding, locates specific binding information and returns a bindingDetail_message that includes the access point, by URL type, for the service

* find_business, the main API for the initial search, finds information about one or more businesses and returns a business list message

* find_relatedbusinesses, finds businesses related to the business key and returns a business list message; checks for subsidiary or other departments for a given business

* find_service, finds and returns specific services listed for a specific business

* find_tmodel, finds and returns tmodel structures, providing a way to search the registry for matching services

* get_bindingDetail, finds and returns bindingTemplate information sufficient for invoking a service hosted by a specific business; returns a bindingDetail message

* get_businessDetail, gets full detail on a specific registered business and returns a businessDetail message, usually a second inquiry once a list of matching businesses is returned by a previous inquiry

* get_businessDetailExt, finds and returns an extended businessDetailExt message; that is the same as get_businessdetail but with extended information defined for after v1

* get_serviceDetail, finds and returns all information about a given set of registered business service information; returns a serviceDetail message

* get_tModelDetail, gets full details for a set of registered tmodel data; returns a tModelDetail message

Inquiry APIs return no values if there's no match for one of the search keys. The APIs include an option to set a maximum number of rows to be returned and a flag to indicate that more rows exist than can be returned. Wildcard searching is available on the find_business API name parameter.

The find_business API, the main search API, can search via name, identifiers, categories, or tModel references and can also search for URLS. Up to five name values are supported for a search. Usually, the first search returns a list of matches to one or more of the criteria.

The find-service API can be used to find specific services that meet specific criteria. You can browse by name on a service, get the UUID for the service, and pass it back in to the find_service API to get the specific service entry.

The binding-detail API gets the information you need to call a service. The information can be cached and refreshed as needed. Extension (Ext) APIs are available for compatibility when things For example, get_businessDetailExt returns the same information as get_businessDetail, plus more info: extensions to UDDI for v2, in other words. Sometimes, the results of one query feed the input for another query. For example, get_businessDetail might return a tModel key from the tModelInstanceinfo associated with the business information; then the next call can use the tModel key to obtain a specific tModel record. Finally, the tModel can be linked to one or more business entity structures to obtain the information necessary to access the service. No authentication is required for inquiry APis. No wire encryption is used.

Publisher APIs

Publisher APis are used to store, to update, and to delete or hide information in the registry. Like all APis that store data, the data being stored ideally takes typical subsequent query operations into account. in other words, appropriate data has to be stored to allow the inquiries to produce meaningful results.

Passing a blank UUID key indicates that the data is being stored for the first time. New or different information with the same UUID replaces the old information. Relationship information can be changed by making changes to the keys that define the relationship information. When businessEntities are registered, the operator site creates a URL that can be used to get the element being registered by using an HTTP GET operation. The publisher APIs allow any number of classification codes to be stored for a business. Classifications include category codes for a business or geographical information. When registering information, a business or an agent has the option of asking for the categorization information to be checked or to remain unchecked, that is, for UDDI to accept any categorization data the business or agent wants to store.

From Understanding Web Services, Addison Wesley

ISBN 0-201-75031-

<element name = "businessEntity">
    <complexType>
       <sequence>
          <element ref = "discoveryURLs" minOccurs = "0" />
          <element ref = "name" maxOccurs = "unbounded" />
          <element ref = "description" minOccurs = "0"
                                       maxOccurs = "unbounded" />
          <element ref = "contacts" minOccurs = "0" />
          <element ref = "businessServices" minOccurs = "0" />
          <element ref = "identifierBag" minOccurs = "0" />
          <element ref = "categoryBag" minOccurs = "0" />
       </sequence>
       <attribute ref = "businessKey" use = "required" />
       <attribute ref = "operator" />
       <attribute ref = "authorizedName" />
    </complexType>
</element>
Figure 4.