The UDDI API Sets
In my previous SOA post I covered the UDDI Information model in a fair amount of detail. While describing the UDDI Information Model I stated that the UDDI specification standardizes two aspects of SOA Metadata. These two aspects are the Information model and the way that the information model is accessed and manipulated. In this post I want to cover this second aspect of UDDI which deals with accessing the UDDI Information Model.
It should be no surprise that the UDDI specification describes all UDDI data access in terms of web services. The UDDI specification uses the term “API Set” to refer to these web services. An API Set is essentially a single web service containing related operations. UDDI specifies 9 API Sets to be used for all forms of data access and data manipulation. The list of UDDI API Sets is shown in Figure 1. The WSDL documents for these services are also shown in Figure 1. These files can be found on the OASIS site.
Having a common API for accessing the information in a SOA Registry is important when an organization is looking to implement design time governance, run time governance, management of a SOA in the data center, and discovery in the software development lifecycle. By having a common API for accessing registry information you can purchase the tools that are right for you and be assured that they will work correctly with your SOA Registry.
|
API Set
|
Types
|
Port Types
|
Bindings
|
|
Inquiry
|
uddi_v3.xsd
|
uddi_api_v3_portType.wsdl
|
uddi_api_v3_binding.wsdl
|
|
Publication
|
uddi_v3.xsd
|
uddi_api_v3_portType.wsdl
|
uddi_api_v3_binding.wsdl
|
|
Security
|
uddi_v3.xsd
|
uddi_api_v3_portType.wsdl
|
uddi_api_v3_binding.wsdl
|
|
CustodyTransfer
|
uddi_v3.xsd
uddi_v3custody.xsd
|
uddi_custody_v3_portType.wsdl
|
uddi_custody_v3_binding.wsdl
|
|
Replication
|
uddi_v3.xsd
uddi_v3replication.xsd
|
uddi_repl_v3_portType.wsdl
|
uddi_replication_v3_binding.wsdl
|
|
Subscription
|
uddi_v3.xsd
uddi_v3subscription.xsd
|
uddi_sub_v3_portType.wsdl
|
uddi_sub_v3_binding.wsdl
|
|
SubscriptionListener
|
uddi_v3.xsd
uddi_v3subscriptionListener.xsd
|
uddi_subr_v3_portType.wsdl
|
uddi_subr_v3_binding.wsdl
|
|
ValueSetValidation
|
uddi_v3.xsd
uddi_v3valueset.xsd
|
uddi_vs_v3_portType.wsdl
|
uddi_vs_v3_binding.wsdl
|
|
ValueSetCaching
|
uddi_v3.xsd
uddi_v3valuesetcaching.xsd
|
uddi_vscache_v3_portType.wsdl
|
uddi_vscache_v3_binding.wsdl
|
Figure 1 – The UDDI API Sets
A Crash course on WSDL
If you are unfamiliar with the WSDL specification and the above table is confusing then here is a crash course on WSDL. The basic structure of a WSDL document is shown in the example of Figure 2.
Figure 2 – The basic structure of a WSDL file
All WSDL documents have a root element named definitions. Within the definitions root there are five high level elements that are used to describe a web service. These elements are: types, message, portType, binding, and service. Below is a description of each of these elements. Figure 3 shows the relationship of these elements to each other.
types - The types element is used to contain all the type definitions needed to understand request messages, create response messages, and create fault messages. If you built your web service with an object oriented language then you will find type definitions that represent your input parameters and return values in this section of the service’s WSDL file.
message – A WSDL document will have multiple message elements. Each message element uses the structures described in types to describe a message that the web service needs to receive or send. For example, two or more definitions found in types may be needed to form a request message or a response message. This includes standard payload data and any Soap headers that may be needed for each message. All request messages, response messages and fault messages are described by a message element.
portType – a portType is a grouping of related operations. Operations are created within the portType element from the messages defined in the message elements described above. This is done by grouping request messages, response messages, and fault messages together to form an operation. For example, a two way operation (a.k.a. request/response) will require one request message, one response message, and one fault message to fully define it. A portType in WSDL is analogous to an interface in an object oriented programming language. It describes the contract for a service but it contains no details about the concrete implementation such as Soap style and network address.
binding – The binding element adds concrete information to each portType. Typically this involves associating a SoapAction to each operation and specifying the SOAP style.
service – The service element associates each binding with a network address. The combination of a binding with a network address is known as a port in the WSDL specification.
Figure 3 – The relationship between types, message, portType, binding, and service
The UDDI API sets which are shown in Figure 1 break this information up into separate files. Type declarations that are used in the types element are placed into xsd files. Notice that uddi_v3.xsd which contains the information model described in my last post is used by all the API sets. (This is an example of data contract and message contract reuse. This type of reuse is not unique to UDDI. All organizations building an Enterprise SOA should consider reuse at the data contract and message contract level.) portTypes are in their own file with a wsdl extension. The port type files contain the portType, message, and types elements. These files import the appropriate xsd files into their types element. bindings are also in their own file with a wsdl extension. They contain the binding element and import the appropriate portType files. The service information is left unspecified by UDDI since this requires the specification of a network address that the API Set will be listening on.
The following sections provide a brief description of the API Sets shown in Figure 1.
Inquiry API Set
This service allows entries in the UDDI registry to be located and detailed information to be returned. Figure 4 shows the operations that make up the Inquiry API Set. Here we see that the Inquiry API Set contains 5 search operations and 5 get operations. The search operations use parameters that allow search criteria to be specified. The get operations allow detailed information about a single UDDI entity to be retrieved.
This is the API set that should be used when searching the registry or when detailed information about an entry is needed.
Figure 4 – The Inquiry API Set
Publication API Set
Operations in this API Set are used to add, update, and delete the core types of the UDDI Information model. These core types are: businessEntities, businessServices, bindingTemplates, and tModels. In addition to managing these core types the Publication API Set also allows publisher assertions to be managed. Publisher assertions in UDDI allow businessEntities to be associated with each other. This is important since many large organizations are not effectively described by a single businessEntity structure. For example, a large company may have several subsidiaries that have different descriptions but are still closely coupled. In this situation publisher assertions allow these subsidiaries to make their relationships visible in a UDDI registry. Finally, the get_registeredInfo API call is used to get an abbreviated list of all businessEntity and tModel data that are controlled by a publisher. Figure 5 shows the operations that make up the Publication API Set.
Figure 5 – The Publication API Set
Security API Set
The Security API set is used to request an authentication token. Registry policy dictates whether the use of an authentication token is required. If required, an authentication token will be needed when using the Inquiry API Set, the Publication API Set, the Custody Transfer API Set, and the Subscription API Set. An authentication token can be acquired using the get_authToken operation. This token is then passed as a parameter to all operations that require authentication. The discard_authToken operation is used to inform the UDDI Registry that the passed authentication token is to be discarded, effectively ending the session.
Figure 6 shows the two operations of the Security API Set.
Figure 6 – The Security API Set
Replication API Set
The UDDI specification supports the concept of UDDI Nodes. A UDDI node is essentially a registry instance. A logical UDDI Registry may be composed of multiple physical nodes which reside in different locations. The Replication API Set provides replication between nodes so that changes made to one node propagate throughout the other nodes in the logical UDDI Registry. Figure 7 shows the operations found in the Replication API Set.
Figure 7 – The Replication API Set
Custody Transfer API Set
During publication of a businessEntity or tModel, a relationship is established between the publisher, the item published, and the node where it was published. By default a publisher that creates a new entry in the registry owns the new entry and has the authority to change it. The Custody and Ownership Transfer API Set enables any nodes of a registry to cooperatively transfer custody of one or more businessEntity or tModel structures from one node to another, as well as allowing the transfer of ownership of these structures from one publisher to another. Associated entities of a businessEntity such as its businessService, bindingTemplate, and publisherAssertion structures are transferred as part of the custody transfer of the business entity.
Figure 8 shows the three operations found in the Custody Transfer API Set.
Figure 8 – The Custody Transfer API Set
Subscription API Set
The Subscription API Set is used to allow registry clients to register requests for tracking new and changed registry content. The operations in this API Set provide functionality for the maintenance of subscriptions and the retrieval of subscription results. save_subscription, get_subscriptions, and delete_subscription allow subscriptions to be created, modified, retrieved and deleted. This API Set also provides an operation (get_subscriptionResults) that returns subscription results. When get_subscriptionResults is executed it returns registry data that has changed for a particular subscription within a specified time period. Figure 9 shows the four operations that make up the Subscription API Set
Figure 9 – The Subscription API Set
Subscription Listener API Set
The Subscription Listener API Set is an optional client API Set. In other words this API Set can be implemented by a UDDI Registry client that is interested in being sent subscription results by the UDDI Registry. The address of the API Set can be setup with a particular subscription and the UDDI Registry will invoke its one operation notify_subscriptionListener passing in data that has changed since notify_subscriptionListener was last invoked for the subscription. Figure 10 shows the one operation that makes up the Subscription Listener API Set.
Figure 10 – The Subscription Listener API Set
Value Set Validation API Set
All of the core types described in my post on the UDDI information model can be categorized utilizing the techniques I described involving categoryBags and tModels. Many times the valid category values will be stored outside of a UDDI Registry by a third party system. The UDDI Specification refers to these third parties as “Value Set Providers”. The Value Set Validation API Set allows these Value Set Providers to register a validation service. This validation service is then invoked for checking purposes before the core types are saved to the UDDI Registry.
This same validation technique can also be used for the businessEntity and the tModel types that have identifierBags that serve to uniquely identify businessEntity instances and tModel instances.
Figure 11 shows the one operation that makes up the Value Set Validation API Set.
Figure 11 – The Value Set Validation API Set
Value Set Caching API Set
This API set can be used instead of the Value Set Validation API Set. If appropriate, all valid third party values may be retrieved and cached by a UDDI Registry. When data is saved to the UDDI Registry these cached values can be used for validation instead of using the Value Set Validation API Set described above. Figure 12 shows the one operation that makes up the Value Set Caching API Set.
Figure 12 – The Value Set Caching API Set
Summary
The UDDI API Sets provide interoperable access to your SOA Metadata. When SOA Metadata can be accessed in an interoperable fashion then organizations are free to choose best of breed products when looking to add design time governance, run time governance, management of a SOA in the data center, and discovery in the software development lifecycle.