|
|
UDDI Spec TC |
UDDI Version 2.04 API Specification
UDDI Committee Specification, 19 July 2002
Document identifier:
ProgrammersAPI_v2
Location:
http://uddi.org/pubs/ProgrammersAPI-V2.04-Published-20020719.htm
Latest version:
http://uddi.org/pubs/ProgrammersAPI_v2.htm
Editors:
Tom Bellwood, IBM
Contributors:
Douglas Bryan, Accenture
Vadim Draluk, BEA
Dave Ehnebuske, IBM
Tom Glover, IBM
Andrew Hately, IBM
Yin Leng Husband, HP
Alan Karp, HP
Keisuke Kibakura, Fujitsu
Chris Kurt, Microsoft
Jeff Lancelle, Verisign
Sam Lee, Oracle
Sean MacRoibeaird, Sun
Anne Thomas Manes, Sun
Barbara McKee, IBM
Joel Munter, Intel
Tammy Nordan, HP
Chuck Reeves, Microsoft
Dan Rogers, Microsoft
Christine Tomlinson, Sun
Cafer Tosun, SAP
Claus von Riegen, SAP
Prasad Yendluri, WebMethods
Acknowledgements:
The UDDI Spec TC recognizes the contributions of other participants from the UDDI.org Working Group:
Jeff Burinda, Wand
Tom Clement, Avinon
Brian Eisenberg, Datachannel
Andy Harris, i2 Technologies
Denise Ho, Ariba
Jared Rodriguez
UDDI Business Registry Operators Council
Abstract:
This document describes the programming interface and expected behaviors of all instances of the Universal Description, Discovery and Integration (UDDI) registry.
Status:
This specification has attained the status of OASIS Standard.
Committee members should send comments on this Committee Specification to the uddi-spec@lists.oasis-open.org list. Others should subscribe to and send comments to the uddi-spec-comment@lists.oasis-open.org list. To subscribe, send an email message to uddi-spec-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.
For information on whether any intellectual property claims have been disclosed that may be essential to implementing this Committee Specification, and any offers of licensing terms, please refer to the Intellectual Property Rights section of the UDDI Spec TC web page (http://www.oasis-open.org/committees/uddi-spec/).
Copyrights
Copyright © 2001-2002 by Accenture, Ariba, Inc., Commerce One, Inc., Fujitsu Limited, Hewlett-Packard Company, i2 Technologies, Inc., Intel Corporation, International Business Machines Corporation, Microsoft Corporation, Oracle Corporation, SAP AG, Sun Microsystems, Inc., and VeriSign, Inc. All Rights Reserved.
Copyright © OASIS Open 2002-2003. All Rights Reserved.
Contents
2.4 Classification and Identification information
4.1 About UDDI Inquiry API functions
4.1.2 Effect of service projections on V1 find_business and find_service calls
4.1.3 Elements whose length exceed the maximum lengths
4.3 About UDDI Publishing API functions
4.3.1 Rationale for UDDI version 2.0 Publishing API Enhancements
4.3.2 Features to help the registry become more useful
4.3.4 Effect of Version 1 save_xx in Version 2 UDDI Registries
4.3.5 Saving categorization and identification information
4.3.6 Special considerations for the xml:lang attribute
4.3.7 Third party opportunities
4.4 Publishing API Function Reference
4.4.4 delete_publisherAssertions
4.4.8 get_assertionStatusReport
4.4.10 get_publisherAssertions
4.4.16 set_publisherAssertions
Appendix A: Error code reference
A.2 Success reporting with the dispositionReport element:
A.3 Error reporting with the dispositionReport element:
Appendix B: SOAP usage details
B.6 XML prefix conventions – default namespace support
B.7 Support for Unicode: SOAP listener behavior
C.1 Support for multiple languages
Appendix D: Security model in the publishers API
D.1 Authentication of publisher API calls
D.1.2 Establishing credentials
D.1.3 Authentication tokens are not portable
D.1.4 Generating Authentication Tokens
E.1 General form of findQualifiers
E.1.1 findQualifiers enumerated
E.1.2 findQualifier Applicability and Precedence
Appendix F: Response message reference
Appendix G: redirection via hostingRedirector element
G.1 Special situations requiring the hostingRedirector
G.2 Using the hostingRedirector data
Appendix H: Checking external value-sets
Appendix I: Utility tModels and Conventions
I.1.2 UDDI Core tModels - built-in taxonomies, identifier systems, and relationships.
I.1.3 UDDI Core tModels – Other
I.2 Registering tModels within the Type Taxonomy
Appendix J: Relationships and publisher assertions
J.2 Managing relationship visibility
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
2.1 Document Overview
This document describes the programming interface and expected behaviors of all instances of the Universal Description, Discovery and Integration (UDDI) registry. The primary audience for this document is programmers who want to write software that will directly interact with a UDDI Operator Site[1]. Private implementations of the UDDI specification should provide support for the interface described here as well as the behaviors defined.
2.1.1 What is UDDI?
Universal Description, Discovery and Integration, or UDDI, is the name of a group of web-based registries that expose information about a business or other entity[2] and its technical interfaces (or API’s). These registries are run by multiple Operator Sites, and can be used by anyone who wants to make information available about one or more businesses or entities, as well as anyone that wants to find that information. There is no charge for using the basic services of these operator sites.[3]
By accessing any of the public UDDI Operator Sites, anyone can search for information about web services[4] that are made available by or on behalf of a business. The benefit of having access to this information is to provide a mechanism that allows others to discover what technical programming interfaces are provided for interacting with a business for such purposes as electronic commerce, etc. The benefit to the individual business is increased exposure in an electronic commerce enabled world.
The information that a business can register includes several kinds of simple data that help others determine the answers to the questions “who, what, where and how”. Simple information about a business – information such as name, business identifiers (D&B D-U-N-S Number®, etc.), and contact information answers the question “Who?” “What?” involves classification information that includes industry codes and product classifications, as well as descriptive information about the services that the business makes available. Answering the question “Where?” involves registering information about the URL or email address (or other address) through which each type of service is accessed[5]. Finally, the question “How?” is answered by registering references to information about interfaces and other properties of a given service. These service properties describe how a particular software package or technical interface functions. These references are called tModels in the UDDI documentation.
2.2 Compatible registries
This specification, coupled with the UDDI API schema (uddiAPI2.xsd) and the information in the UDDI Version 2.0 Data Structure Reference, defines a programming interface that is available according to the licensing terms defined in the beginning of this document. Software developers, businesses and others are encouraged to define products and tools that make use of both public and private UDDI registries. Developers who license this specification are further encouraged to build registries that are compatible with the UDDI specifications.
2.3 What are tModels?
In order for two or more pieces of software to be compatible with each other – that is, compatible enough to be able to exchange data for the purpose of achieving a desirable result – they must share some design goals and specifications in common. The registry information model that each UDDI site supports is based on this notion of shared specifications.
In the past, to build compatible software, two companies only had to agree to use the same specification, and then test their software. However, within a UDDI registry, businesses need a way to publish information about the specifications and versions of specifications that were used to design their advertised services. To accommodate the need to distinctly identify public specifications (or even private specifications shared only with select partners), information about the specifications themselves needs to be discoverable. This information about specifications – a classic metadata construct – is called a tModel within UDDI.
The tModel mechanism serves a useful purpose in discovering information about interfaces and other technical foundation concepts that are exposed for broad use by an individual service or registration instance. To get a clearer understanding, let’s consider an example.
2.3.1 An example:
Suppose your business bought a software package that let you automatically accept electronic orders via your Internet connection. Using one of the public UDDI operator sites, you could “advertise” the availability of this electronic commerce capability so that your partners and customers could find out that you can accept orders electronically.
One of the reasons you chose this particular software package was its widespread popularity. In fact the salesperson that sold you the software made a point of highlighting a feature that gives your new software its broad appeal – the use and support of a widely used electronic commerce interface that accommodates automatic business data interchange.
As you installed and configured your new software, this software automatically consulted one of the public UDDI sites and identified compatible business partners. It did this by looking up each business you identified, and located those that had already advertised support for electronic commerce services that are compatible with your own.
The configuration software accomplishes this by taking advantage of the fact that a tModel has been registered within UDDI and a corresponding tModel key (called a tModelKey) gets assigned at the time of registration. This tModel represents the interface or specification for the electronic commerce capability. Individual partner capabilities are stored within UDDI as information about service bindings[6] – and each of these bindings references the tModel that represents the specific interface that your software understands.
In general, it’s pretty safe to think of the tModel keys within a services binding description as a fingerprint that can be used to trace the compatibility origins of a given service. Since many such services will be constructed or pre-programmed to be compatible with a given, well-known interface, references to the tModel serve to identify the properties associated with a given service binding.
For software companies and programmers, tModels provide a common point of reference that allows a technical interface to be registered, and compatible implementations of those interfaces to be easily identified. For businesses that use software, the benefit is greatly reduced work in determining which particular bindings exposed by a business partner are compatible with the software used in-house. Finally, for standards organizations, the ability to register information about a specification and then find implementations of web services that are compatible with a standard helps customers immediately realize the benefits of a widely used design.
2.4 Classification and Identification information
One of the immediate benefits of registering business information at one of the UDDI Operator Sites is the ability to specify one or more classifications, or category codes for your business. Many such codes exist – NAICS, UN/SPC, SIC Codes, etc. – and are widely used to classify businesses, industries, and product categories. Other (and there are many) classifications designate geographic information, or membership in a given organization.
The UDDI programming interface (API) defines a consistent way for businesses to add any number of classifications to their business registrations. This information, in turn, allows simple searching to be done on the information contained in the public registries. More importantly, registering information such as industry codes, product codes, geography codes and business identification codes (such as D&B D-U-N-S Numbers®) allows other search services to use this core classification information as a starting point to provide added-value indexing and classification while still referencing your UDDI information.
The UDDI version 2 specifications add the ability to accommodate validated classification and identification taxonomies. This new capability allows any company to extend the support that all UDDI operators use to manage validated taxonomies. In UDDI version 2, two types of taxonomies are supported that were not possible in UDDI version 1. These are unchecked and checked categorization and identification taxonomies.
Unchecked taxonomies are used for categorization and identification without the need for UDDI to perform a specific call-out to a validation service. Organizations that choose to make a particular taxonomy available for categorization or identification can register a taxonomy and use that taxonomy as unchecked. Unchecked taxonomies are registered by simply registering a new tModel, and classifying that tModel as either an identifier or as a categorization taxonomy.
Checked taxonomies are used when the publisher of a taxonomy wishes to make sure that the categorization code values or identifiers registered represent accurate and validated information. UDDI version 2 supports third parties that wish to create new checked taxonomies of identifiers and categorizations.
The UDDI programmer’s API is designed to provide a simple request/response mechanism that allows discovery of businesses, services and technical service binding information.
3.1 Design Principles
The primary principle guiding the design of this programmer’s API was simplicity. Care has been taken to avoid complexity, overlap, and also to provide direct access to the appropriate levels of registered information with a minimum of programming overhead and round tripping.
3.1.1 Security
Accessing UDDI programmatically is accomplished via API calls defined in this programmer’s reference. Two types of APIs are defined. A publisher's API is provided for interactions between programs and the UDDI registry for the purpose of storing or changing data in the registry. An inquiry API is provided for programs that want to access the registry to read information from the registry.
Authenticated access is required to use the publishers API. Each Operator Site is responsible for selecting and implementing an authentication protocol that is compatible with the publishers API, as well as providing a new user sign-up mechanism. Before using any of the publisher API functions, the caller is responsible for signing up with one or more Operator Sites or compatible registries and establishing user credentials.
The Inquiry and Publishers API functions are exposed as SOAP messages over HTTP. HTTPS (specifically SSL 3.0) is used for all publisher API calls in order to assure wire privacy. No authentication is required to make use of the Inquiry API functions.
3.1.2 Versioning
In any programmers API, as well as any message set, versioning issues arise as time passes. Changes to an API over time can result in requests being misunderstood or processed incorrectly unless one can determine whether the version of the API being provided matches the version of the API used by a requesting party.
In order to facilitate a proper and controlled version match, the entire API defined by this programmer’s reference is version stamped. Since the API itself is based on XML messages transmitted in SOAP envelopes over HTTP[7], this version stamp takes the form of an XML attribute.
All of the messages defined in this API must be transmitted with an accompanying application version attribute. This attribute is named “generic[8]” and is present on all messages. Each time this specification is modified, an ensuing requirement is placed on all Operator Sites to support generic 1, the current generic and at least the previous generic, if any. Compatible registries are encouraged to support at a minimum the generic 1 version of the UDDI API.
The use of generic value 1.0 with the UDDI version 2.0 namespace, or generic value 2.0 with the UDDI version 1 namespace is not considered to be a normal use of the versioning mechanism. Individual operators are permitted to interpret mixed versioning information as an error condition.
3.1.3 SOAP Messaging
SOAP is a method for using Extensible Markup Language (XML) in message and remote procedure call (RPC) based protocols. SOAP has been jointly defined and submitted to the World Wide Web consortium (W3C) as a note.
UDDI uses SOAP in conjunction with HTTP to provide a simple mechanism for passing XML messages to Operator Sites using a standard HTTP-POST protocol. Unless specified, all responses will be returned in the normal HTTP response document. As of version 2, there are still no interactions that deviate from this general rule.
See the appendix on SOAP-specific implementations for more information on the way that UDDI Operator Sites use the SOAP schema as an envelope mechanism for passing XML messages.
3.1.4 XML conventions
The programming interface for UDDI is based on Extensible Markup Language (XML). See the appendix (XML usage details) for more information on specific XML constructs and limitations used in the specification of the programmer's interface.
3.1.5 Error Handling
The first line of error reporting is governed by the SOAP specification. SOAP fault reporting and fault codes will be returned for most invalid requests or any request where the intent of the caller cannot be determined.
If any application level error occurs in processing a request message, a dispositionReport structure will be returned to the caller inside of a SOAP fault report. Faults that contain disposition reports contain error information that includes descriptions and typed keys that can be used to determine the cause of the error. Refer to the appendix “Error Codes” for a general understanding of error codes. API-specific interpretations of error codes are described following each API reference page.
Many of the API constructs defined in this document allow one or more of a given type of information to be passed. These API calls each conceptually represent a request on the part of the caller. The general error handling treatment recommended for UDDI operators is to detect errors in a request prior to processing the request. Any errors in the request detected will invalidate the entire request, and cause a dispositionReport to be generated within a SOAP Fault structure (see appendix A).
In the case of an API call that involves passing multiples of a given structure, the dispositionReport will call out only the first detected error, and is not responsible for reporting multiple errors or reflecting intermediate “good” data. In situations where a specific reference within a request causes an error to be generated, the corresponding disposition/fault report will contain a clear indication of the key value that caused the rejection of the rejected request.
In general, UDDI Operators may return any UDDI error code needed to describe an error. The error codes specified within each API call description are characteristic of the API call, but other UDDI error codes may be returned in unusual circumstances or when doing so adds additional descriptive information.
3.1.6 White Space
With one exception, Operator Sites and compatible implementations will store white space contained in data exactly as it is provided. The exception is that, where the UDDI schema permits the appearance of leading and/or trailing white space, it will be removed from each field, element or attribute. White space SHOULD NOT be present where the UDDI schema does not allow it. Operator Sites and compatible implementations SHOULD reject requests that contain such white space. White space characters include carriage returns, line feeds, spaces, and tabs. UDDI Operators will not allow “name” fields (where entities are named) to be empty.
3.1.7 XML Encoding
For the purpose of this specification and all UDDI Operator Sites, consistency in handling of data is essential. For this reason, the default collation order for data registered within an Operator Site is binary even though this choice is meaningless for some languages, and effectively favors alphabetic languages. Similarly, XML allows for a large number of character set encoding choices. UDDI Operators are required to only support a single XML encoding – UTF-8, and will support all compatibility characters defined for UTF-8. See appendix B for more information related to the use of byte order marks and UTF-8 and the way the UDDI SOAP implementations convert all requests to Unicode prior to processing.
This API reference is divided into 3 logical sections, each addressing a particular programming focus. These sections each cover the inquiry API, the publishing API, and appendices that describe specific concepts, technical details, UDDI extensions or added background information.
The special values within API syntax examples are shown in Italics. In most cases, the following reference applies to these values:
· uuid_key: Access keys within all UDDI defined data elements are represented as universal unique identifiers (these are sometimes called a GUID). The name of the element or attribute designates the particular key type that is required. These keys are always formatted according to an algorithm that is agreed upon by the UDDI Operator Council with the one exception being tModelKey values, which are prefixed with a URN qualifier in the format "uuid:" followed by the UUID value.
· generic: This special attribute is a required metadata element for all messages. It is used to designate the specification version used to format the SOAP message. In the 1.0 version of the specification, this value is required to be “1.0". In the 2.0 version of the specification, this value is required to be “2.0”. As of the date this specification, any other value (e.g. not “1.0” and not “2.0”) passed will result in an E_unsupported error.
· xmlns: This special attribute is a required metadata element for all messages. Technically, it isn’t an attribute, but is formally called a namespace qualifier. It is used to designate a universal resource name (URN) value that is reserved for all references to the UDDI schema. In the 1.0 version of the specification, this value is required to be “urn:uddi-org:api". In the 2.0 version of the specification, this value is required to be “urn:uddi-org:api_v2”.
· findQualifiers: This special element is found in the inquiry API functions that are used to search (i.e., the messages named find_binding, find_business, find_relatedBusinesses, find_service, and find_tModel). This passed argument is used to signal special behaviors to be used with searching. See the findQualifiers appendix and the documentation for the individual find API messages for more information.
· maxRows: This special qualifier is found in the inquiry API functions that are used to search (e.g. find_binding, find_business, find_service, and find_tModel). This argument is used to limit the number of results returned from a request. When an Operator Site or compatible instance returns data in response to a request that contains this caller-supplied limiting argument, the number of main result elements will not exceed the integer value passed. If a result set is truncated as a result of applying this limit, or if a result set is truncated because the search would otherwise exceed an operator-specific limit, the result will include the truncated attribute with a value of true.
· truncated: The truncated attribute indicates that the results returned do not represent the entire query result set. The actual limit set for applying this treatment is Operator Site policy specific, but in general should be a sufficiently large number so as to not normally be an issue. No behaviors such as paging mechanisms are defined for retrieving more data after a truncated limit. The intent is to support the average query, while at the same time allowing Operator Sites the leeway required to be able to manage adequate performance. UDDI is not designed to support large data sets required by some research uses.
· categoryBag: Searches can be performed based on a cross section of categories. Several categories are broadly supported by all Operator Sites and provide three categorization dimensions. These are industry type, product or service type, and geography. Searches involving category information can be combined to cross multiple dimensions[9]. For this reason, these searches are performed by default matching on ALL of the categories supplied (e.g. logical AND). In general, the embedded category information serves as voluntary hints that depend on how the registering party has categorized themselves, but not to provide a full third party categorization facility.
· identifierBag: Searches involving identifiers are performed matching on any supplied identifier (e.g. D&B D-U-N-S Number®, etc) for any of the primary elements that have identifierBag elements. These searches allow broad identity matching by returning a match when any keyedReference set used to search identifiers matches a registered identifier. Version 2 provides for the definition of checked identifiers. This enhancement makes it possible to distinguish copycat information within UDDI from the registrations of the authentic business registration based on validated identifiers.
· tModelBag: This element is found in the inquiry messages named find_business, find_service, and find_binding. Searches that match a particular technical fingerprint use UUID values to search for bindingTemplates with matching tModelKey value sets. When used to search for web services (e.g. the data described by a bindingTemplate structure), the concept of tModel fingerprints allows for highly selective searches for specific combinations of keys. For instance, the existence of a web service that implements all of the parts of the UDDI specifications can be accomplished by searching for a combination of tModel key values that correspond to the full set of specifications (the UDDI specification, for instance, is divided into at least 3 different, separately deployable tModels). At the same time, limiting the number of tModelKey values passed in a search can perform broader searches that look for any web service that implements a specific sub-part of the full specification. All tModelKey values are always expressed using a Uniform Resource Identifier (URI) format that starts with the characters "uuid:" followed by a formatted Universally Unique Identifier (UUID) consisting of Hexadecimal digits arranged in the common 8-4-4-4-12 format pattern.
In all cases, the XML structures, attributes and element names shown in the API examples are derived from the Message API schema. For a full understanding of structure contents, refer to this schema as well as the UDDI data structure reference. It is suggested that tools that understand schemas be used to generate logic that populates the structures used to make the API calls against UDDI.
4.1 About UDDI Inquiry API functions
4.1.1 Three query patterns
The Inquiry API provides three forms of query that follow broadly used conventions which match the needs of software traditionally used with registries.
4.1.1.1 The browse pattern
Software that allows people to explore and examine data – especially hierarchical data – requires browse capabilities. The browse pattern characteristically involves starting with some broad information, performing a search, finding general result sets and then selecting more specific information for drill-down.
The UDDI API specifications accommodate the browse pattern by way of the find_xx API calls. These calls form the search capabilities provided by the API and are matched with summary return messages that return overview information about the registered information that is associated with the inquiry message type and the search criteria specified in the inquiry.
A typical browse sequence might involve finding whether a particular business you know about has any information registered. This sequence would start with a call to find_business, perhaps passing the first few characters of a business name that you already know. This returns a businessList result. This result is overview information (keys, names and descriptions) derived from the registered businessEntity information, matching on the name fragment that you provided.
If you spot the business you are looking for within this list, you can drill down into the corresponding businessService information, looking for particular service types (e.g. purchasing, shipping, etc) using the find_service API call. Similarly, if you know the technical fingerprint (tModel signature) of a particular software interface and want to see if the business you’ve chosen provides a web service that supports that interface, you can use the find_binding inquiry message.
4.1.1.2 The drill-down pattern
Once you have a key for one of the four main data types managed by a UDDI or compatible registry[10], you can use that key to access the full registered details for a specific data instance. The current UDDI data types are businessEntity, businessService, bindingTemplate and tModel. You can access the full registered information for any of these structures by passing a relevant key type to one of the get_xx API calls.
Continuing the example from the previous section on browsing, one of the data items returned by all of the find_xx return sets is key information. In the case of the business we were interested in, the businessKey value returned within the contents of a businessList structure can be passed as an argument to get_businessDetail. The successful return to this message is a businessDetail message containing the full registered information for the entity whose key value was passed. This will be a full businessEntity structure.
4.1.1.3 The invocation pattern
In order to prepare an application to take advantage of a remote web service that is registered within the UDDI registry by other businesses or entities, you need to prepare that application to use the information found in the registry for the specific service being invoked. This type of inter-business service call has traditionally been a task that is undertaken at development time. This will not necessarily change completely as a result of UDDI registry entries, but one significant problem can be managed if a particular invocation pattern is employed.
The bindingTemplate data obtained from the UDDI registry represents the specific details about an instance of a given interface type, including the location at which a program starts interacting with the service. The calling application or program should cache this information and use it to contact the service at the registered address whenever the calling application needs to communicate with the service instance. Tools have automated the tasks associated with caching (or hard coding) location information in previously popular remote procedure technologies. Problems arise however when a remote service is moved without any knowledge on the part of the callers. Moves occur for a variety of reasons, including server upgrades, disaster recovery, and service acquisition and business name changes.
When a call fails using cached information previously obtained from a UDDI registry, the proper behavior is to query the UDDI registry for fresh bindingTemplate information. The proper call is get_bindingDetail passing the original bindingKey value. If the data returned is different from the cached information, the service invocation should automatically retry the invocation using the fresh information. If the result of this retry is successful, the new information should replace the cached information.
By using this pattern with web services, a business using a UDDI Operator Site can automate the recovery of a large number of partners without undue communication and coordination costs. For example, if a business has activated a disaster recovery site, most of the calls from partners will fail when they try to invoke services at the failed site. By updating the UDDI information with the new address for the service, partners who use the invocation pattern will automatically locate the new service information and recover without further administrative action.
4.1.2 Effect of service projections on V1 find_business and find_service calls
In version 2 of UDDI the concept of “service projections”[11] which allows a businessEntity to advertise the businessService of another businessEntity as if it were its own. Because service projections are not available in UDDI Version 1, they never appear in the result set of a Version 1 find_business or find_service inquiry.
4.1.3 Elements whose length exceed the maximum lengths
The maximum length of the various UDDI data elements is documented in the UDDI V2.0 Data Structure Reference, Appendix D. These length maxima also apply to data passed in the inquiry APIs. If the length of an element passed in an inquiry API exceeds its documented maximum length, the registry will behave as if the element had been truncated at its maximum length. For example, the maximum length for a <name/> is 255 characters. If a name is passed to find_business that is longer than this, the registry will behave as if only the first 255 characters of the name had been passed.
4.2 Inquiry API functions
The messages in this section represent inquiries that anyone can make of any UDDI Operator Site at any time. These messages all behave synchronously and are required to be exposed via HTTP-POST only. Other synchronous or asynchronous mechanisms may be provided at the discretion of the individual UDDI Operator Site or UDDI compatible registry.
The publicly accessible queries are:
· find_binding: Used to locate specific bindings within a registered businessService. Returns a bindingDetail message.
· find_business: Used to locate information about one or more businesses. Returns a businessList message.
· find_relatedBusinesses: Used to locate information about businessEntity registrations that are related to a specific business entity whose key is passed in the inquiry. The Related Businesses feature is used to manage registration of business units and subsequently relate them based on organizational hierarchies or business partner relationships. Returns a relatedBusinessesList message.
· find_service: Used to locate specific services within a registered businessEntity. Returns a serviceList message.
· find_tModel: Used to locate one or more tModel information structures. Returns a tModelList structure.
· get_bindingDetail: Used to get full bindingTemplate information suitable for making one or more service requests. Returns a bindingDetail message.
· get_businessDetail: Used to get the full businessEntity information for one or more businesses or organizations. Returns a businessDetail message.
· get_businessDetailExt: Used to get extended businessEntity information. Returns a businessDetailExt message.
· get_serviceDetail: Used to get full details for a given set of registered businessService data. Returns a serviceDetail message.
· get_tModelDetail: Used to get full details for a given set of registered tModel data. Returns a tModelDetail message.
4.2.1 find_binding
The find_binding API call returns a bindingDetail message that contains zero or more bindingTemplate structures matching the criteria specified in the argument list.
4.2.1.1 Syntax:
<find_binding serviceKey="uuid_key" [maxRows="nn"] generic="2.0"
xmlns="urn:uddi-org:api_v2" >
[<findQualifiers/>]
<tModelBag/>
</find_binding>
4.2.1.2 Arguments:
· serviceKey: This uuid_key is used to specify a particular instance of a businessService element in the registered data. Only bindings in the specific businessService data identified by the serviceKey passed will be searched.
· maxRows: This optional integer value allows the requesting program to limit the number of results returned.
· findQualifiers: This optional collection of findQualifier elements can be used to alter the default behavior of search functionality. See the findQualifiers appendix for more information.
· tModelBag: This is a list of tModel uuid_key values that represents the technical fingerprint of a bindingTemplate structure contained within the businessService specified by the serviceKey value. Only bindingTemplates that contain all of the tModel keys specified will be returned (logical AND). The order of the keys in the tModel bag is not relevant.
4.2.1.3 Returns:
This API call returns a bindingDetail message upon success. In the event that no matches were located for the specified criteria, the bindingDetail structure returned will be empty (i.e., it contains no bindingTemplate data.) This signifies a zero match result. If no arguments are passed, a zero-match result set will be returned.
In the event of an overly large number of matches (as determined by each Operator Site), or if the number of matches exceeds the value of the maxRows attribute, the Operator site will truncate the result set.. If this occurs, the response message will contain the truncated attribute with the value “true”.
4.2.1.4 Caveats:
If any error occurs in processing this API call, a dispositionReport element will be returned to the caller within a SOAP Fault. The following error number information will be relevant:
· E_invalidKeyPassed: signifies that the uuid_key value passed did not match with any known serviceKey or tModelKey values. The error structure will signify which condition occurred first, and the invalid key will be indicated clearly in text.
· E_unsupported: signifies that one of the findQualifier values passed was invalid. The invalid qualifier will be indicated clearly in text.
4.2.2 find_business
The find_business API call returns a businessList message that matches the conditions specified in the arguments.
4.2.2.1 Syntax:
<find_business [maxRows="nn"] generic="2.0" xmlns="urn:uddi-org:api_v2" >
[<findQualifiers/>]
[<name/> [<name/>]…]
[<discoveryURLs/>]
[<identifierBag/>]
[<categoryBag/>]
[<tModelBag/>]
</find_business>
4.2.2.2 Arguments:
· maxRows: This optional integer value allows the requesting program to limit the number of results returned.
· findQualifiers: This collection of findQualifier elements can be used to alter the default behavior of search functionality. See the findQualifiers appendix for more information.
·
name: This optional collection of string values
represents one or more names potentially qualified with xml:lang attributes.
Wildcard searching[12] can be accomplished
using the % character. The businessList returned contains businessInfo
structures for businesses whose name matches the value(s) passed.
UDDI normally performs a search as though a trailing wildcard had been
specified, resulting in matches on the initial portion of the search argument.
(The initial portion is the left-most portion in left-to-right languages.) This
behavior occurs whenever a find operation is performed that does not specify
the exactNameMatch search qualifier. For that reason it is not necessary for
the user to add a trailing wildcard for this type of search. The user may
override this behavior by including wildcards in the find message. For
example, (assuming a left-to-right language)
<name>Super%docious</name> specified in a find_business would match
any business name which begins with “Super” and ends with “docious”. If the
user wishes this to be a left-most match, the name may be specified as
<name>Super%docious%</name>. This matches any business name which
begins with “Super” and contains the characters “docious” anywhere to the right
of the characters “Super”. If multiple name values are passed, the match occurs
on a logical OR basis.
Each name may be marked with an xml:lang adornment. If provided, the adornment
doesn't need to be unique within the message. If a language markup is
specified, the search results will report a match only on those entries that
match both the name value and language criteria. The match on language is a
leftmost comparison of the characters supplied. This allows one to find all
businesses whose name begins with an "A" and are expressed in any
dialect of French, for example. No restrictions are placed on the values that
can be passed in the language criteria adornment.
· identifierBag: This is a list of business identifier references. The returned businessList contains businessInfo structures matching any of the identifiers passed (logical OR by default). When determining whether a keyedReference matches a passed keyedReference, a match occurs if and only if 1)the tModelKeys refer to the same tModel and 2) the keyValues are identical. The keyNames are not significant.
· categoryBag: This is a list of category references. The returned businessList contains businessInfo elements matching all of the categories passed (logical AND by default). UDDI Version 2.0 defines special findQualifiers that affect categoryBag treatment. When determining whether a keyedReference matches a passed keyedReference, a match occurs if and only if:
1) The tModelKeys refer to the same tModel. In deciding on this, an omitted tModelKey or an empty tModelKey (i.e., tModelKey="") is treated as though the tModelKey for uddi-org:general_keywords had been specified;
2) The keyValues are identical; and
3) If the tModelKey involved is that of uddi-org:general_keywords, the keyNames are identical. Otherwise keyNames are not significant. Omitted keyNames are treated as identical to empty (zero length) keyNames.
· tModelBag: The registered businessEntity data contains a bindingTemplates element that in turn contains bindingTemplate elements that contain specific tModel references. The tModelBag argument lets you search for businesses that have bindings that expose a specific fingerprint within the tModelInstanceDetails collection. The returned businessList contains businessInfo structures that provide a summarized view of registered businessEntity data that contains bindingTemplate structures that match all of the tModel keys passed (logical AND by default)
· discoveryURLs</