The UDDI API at a Glance

A UDDI registry basically answers the following questions:

Who? It identifies the business entity offering the service.
What? Classification information sheds light on what the business purports to offer, as well as all service descriptions.
Where? It identifies the service location (such as a URL for an HTTP binding or an e-mail address for SMTP binding).
How? It provides information on the technical interface or process for the service, called tModel s.

The API affords clients a number of search methods :

They can search by business name . This is known as the "white pages" search method, directly alluding to the telephone directory white pages.
They can search by business category. This is known as the "yellow pages" search method, directly alluding to the telephone directory yellow pages. Here, you use the categoryBag and identifierBag attributes to specify search parameters.
After you find a business, you can query its specific service interface details by using bindingTemplate and tModel , called the "green pages."
A tModel likely describes a standard service interface that many businesses in the same problem space may support. If you already have the tModel at hand (identified by a tModelKey ), you can also conduct a search for all businesses that support that tModel .

The UDDI API utilizes certain data "structures," although they are not programming data structures like those you would use in Java. Rather, they are units of structured XML data used in the UDDI API SOAP messages and responses. The main structures include the following (this list is not exhaustive):

BusinessEntity ” Represents a business that offers some Web service. It carries information such as business name, description, and contacts.
BusinessService ” Represents a particular business service being offered and includes information such as its service name, description, classification (via categoryBag construct), and bindingTemplate (s).
BindingTemplate ” A binding of a service to a particular transport (such as SOAP) and protocol (such as HTTP).
tModel ” A service interface definition that is not tied to any particular binding or provider. This abstract and reusable service definition can be referenced by any number of businessEntities offering the same service. For instance, a standardized Payment Authorization service might have an industrywide tModel defined.

Refer to the UDDI Data Structures specification for more information; it is available at http://www.uddi.org/pubs/DataStructure_v2.pdf.

UDDI Usage Patterns

To understand the intended UDDI interaction paradigm, you need to look at three query patterns:

Browse pattern ” You start with some broad information such as a business name and perform a search by name. From the results returned, you then drill down to its list of service offerings. When you find a desired service, you then find its available bindings and so on. This pattern emphasizes broad navigation, without getting deep into any item, as illustrated by actions 1, 2, 3, and 4 in Figure 31.2.

Figure 31.2. UDDI Inquiry usage patterns.
Drill-down pattern ” Obtaining a key using the Browse pattern, you can find all detailed, registered information available. This pattern is illustrated in Figure 31.2 for any series of actions involving 1A, 2A, 3A, and 4A.
Invocation pattern ” By drilling down to the "green pages" (actions 3A and 4A in Figure 31.2), you can glean technical interface information necessary for you to understand what message structure must be used to invoke a service. This knowledge can be codified during development, whereas some other information can be dynamically cached (such as service endpoints) and the cache refreshed as necessary (as runtime UDDI queries reveal).

A Sample Use Case

Suppose you heard about a company called WeatherCentral that offers a weather report service, and you need to find out where that service is located and how to invoke it. You can use a combination of the Browse and Drill-down patterns by starting a white pages search for the business entity by name. Then you can find the appropriate service category, from which you can examine the service's possible bindings (HTTP-based or SMTP-based and so on) and its tModel . From there, you should have all the information you need to invoke the weather Web service.

The Inquiry API

The Inquiry API messages are for browsing or searching the UDDI registry, and because these functions are strictly read-only, no authentication is required to invoke them. Table 31.1 lists the two groups of inquiry messages: the Find group, which returns overview information, and the Obtain Details group , which returns all information about an item. These are the main Inquiry API calls; this list is not exhaustive. (The response message type is shown in parentheses.)

Table 31.1. Main Inquiry API Messages

	Business	Service	Binding	`tModel`
Find	`find_business (businessList)`	`find_service (serviceList)`	`find_binding (bindingDetail)`	`find_tModel (tModelList)`
Obtain Details	`Get_businessDetail (businessDetail)`	`Get_serviceDetail (serviceDetail)`	`Get_bindingDetail (bindingDetail)`	`Get_tModelDetail (tModelDetail)`

The Publish API

The Publish API messages are for publishing your business, service, binding, or tModel to the UDDI registry. Because these functions alter the registry, authentication is required for invoking these calls. An opaque token must first be obtained from the target UDDI operator by invoking the get_authToken call, which returns an authentication token that is valid for use only with publishing to that particular UDDI operator. That is, opaque tokens are not portable.

Note

When you are done publishing with that UDDI operator, you should send it a discard_authToken message.

Table 31.2 lists the main publish API messages (this list is not exhaustive).

Table 31.2. Main Publish API Calls

	Business	Service	Binding	`tModel`
Create New	`save_business`	`save_service`	`save_binding`	`save_tModel`
Delete	`delete_business`	`delete_service`	`delete_binding`	`delete_tModel`

What a UDDI SOAP Call Looks Like

It's time to see exactly what SOAP messages are being sent and returned when a UDDI API call is made. Here, you will look at the find_service invocation, which searches a given businessEntity (identified by the businessKey attribute) for certain services based on matching criteria: in this case, that the service name matches Authorize Payment . Listing 31.1 shows the UDDI SOAP request.

Listing 31.1 SOAP Request for the `find_service` UDDI Invocation

 <Envelope xmlns=... >   <Body> <find_service businessKey="D8J4D980-78W7-33L4-98745DRF9909"    generic="1.0" xmlns="urn:uddiorg:api">    <name>Authorize Payment</name> </find_service>   </Body> </Envelope>

Listing 31.2 shows the UDDI SOAP response.

Listing 31.2 SOAP Response from the `find_service` UDDI Call

 <Envelope xmlns=...>   <Body> <serviceList generic="1.0" operator="UDDIOperator"    truncated="false" xmlns="urn:uddi-org:api">    <serviceInfos>       <serviceInfo businessKey="D8J4D980-78W7-33L4-98745DRF9909"          serviceKey="BGRG3457-7D2G-44K6-9YU5-G0L4488K893E">       <name>Authorize Payment</name>    </serviceInfos> </serviceList>    </Body> </Envelope>

In any of the find_ xxx calls, you can also specify a service classification by using categoryBag and/or identifierBag as a search parameter.