# 15. Web Services

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Web Services
SOAP
WSDL
WS-Security (WSS) Support in Virtuoso SOAP Server
Web Services Routing Protocol (WS-Routing)
Web Services Reliable Messaging Protocol (WS-ReliableMessaging)
Web Services Trust Protocol (WS-Trust)
XML for Analysis Provider
XML-RPC support
SyncML
UDDI
Concepts Dealing with SOAP Supported API Calls Authorization Mechanism UDDI API Calls Examples
Exposing Persistent Stored Modules as Web Services
Testing Web Published Web Services
BPEL Reference
XSQL

## 15.10. UDDI

### 15.10.1. Concepts

Universal Description, Discovery and Integration (UDDI) is the name of a web-based service that exposes information about a business or other entities and its technical interfaces or APIs. These services are run by UDDI-enabled servers, and can be used by any business that wants to make their information available, as well as anyone who wants to find that information. There is no charge for using the basic services of these sites.

By accessing any of the public sites, anyone can search for information about web services that are made available by or on behalf of a business. This provides a mechanism that allows others to discover what technical programming interfaces are provided for interacting with a business for such purposes as electronic commerce. The benefit to the individual business is increased exposure in an electronic commerce enabled world.

Businesses can register several kinds of simple data to help others answer questions of "who, what, where and how." Simple information about a business - information such as name, business identifiers (D&B D-U-N-S Number(R), etc.), and contact information answers the question "Who." "What" involves classification information including industry codes and product classifications, as well as descriptive information about the services that are available for electronic interchange. Answering the question "Where" involves registering information about the URL or email address (or other address) through which each type of service may be accessed. Finally, the question "How" is answered by registering references to information about specifications that describe how a particular software package or technical interface functions. These references are called 'tModels' in the documentation.

### 15.10.2. Dealing with SOAP

UDDI API functions are exposed as SOAP v1.1 messages over the HTTP protocol. In version 1, the SOAPAction HTTP Header is required. The value passed in this HTTP Header must be an empty string that is surrounded by double quotes.

UDDI and Soap

    POST /UDDI/inquiry HTTP/1.1
    Host: www.foo.com
    Content-Type: text/xml
    Content-Length: nnnn
    SOAPAction: ""

    .... body follows ....

SOAP is used in conjunction with HTTP to provide a simple mechanism for passing XML messages to UDDI-enabled servers using a standard HTTP-POST protocol. Unless specified, all responses will be returned in the normal HTTP response document.

See Also:

For more information about Virtuoso's SOAP Implementation see the SOAP Services section.

### 15.10.3. Supported API Calls

The UDDI APIs always return a SOAP entity body which contains messages as described in UDDI v1 XML Schema (uddi_1.xsd).

- Authorization API - Used to establish authentication mechanism (tokens), dropping already established connections.

  - discard_authToken: Used to inform a UDDI enabled server that a previously provided authentication token is no longer valid.
  - get_authToken: Used to request an authentication token from a UDDI-enabled server. Authentication tokens are required to use all other APIs defined in the publishers API. This function serves as the program's equivalent of a login request.
  - get_registeredInfo: Used to request an abbreviated synopsis of all information currently managed by a given individual.

- Searching API 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_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 full businessEntity information for one or more businesses. 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.

- Repository Manipulation API

  - delete_binding: Used to remove an existing bindingTemplate from the bindingTemplates collection that is part of a specified businessService structure.
  - delete_business: Used to delete registered businessEntity information from the registry.
  - delete_service: Used to delete an existing businessService from the businessServices collection that is part of a specified businessEntity.
  - delete_tModel: Used to delete registered information about a tModel. If there are any references to a tModel when this call is made, the tModel will be marked deleted instead of being physically removed.
  - save_binding: Used to register new bindingTemplate information or update existing bindingTemplate information. Use this to control information about technical capabilities exposed by a registered business.
  - save_business: Used to register new businessEntity information or update existing businessEntity information. Use this to control the overall information about the entire business. Of all the save APIs this one has the broadest effect.
  - save_service: Used to register or update complete information about a businessService exposed by a specified businessEntity.
  - save_tModel: Used to register or update complete information about a tModel.

### 15.10.4. Authorization Mechanism

The Publishers API describes the messages that are used to control the content contained within a UDDI-enabled server, and can be used by compliant non-operator implementations that adhere to the behaviors described in this programmer's reference specification.

All calls made to UDDI-enabled servers that use the messages defined in the publisher's API will be transported using SSL encryption. UDDI-enabled servers will each provide a service description that exposes a bindingTemplate that makes use of HTTPS and SSL to secure the transmission of data.

#### 15.10.4.1. Authentication

Each of the calls in the publisher's API that change information at a given UDDI-enabled server requires the use of an opaque authentication token. These tokens are generated by or provided by each UDDI-enabled server independently, and are passed from the caller to the UDDI-enabled server in the element named authInfo.

These tokens are meaningful only to the UDDI-enabled server that provided them and are to be used according to the published policies of a given UDDI-enabled server.

Each party that has been granted publication access to a given UDDI-enabled server will be provided a token by the site. The methods for obtaining this token are specific to each UDDI-enabled server.

#### 15.10.4.2. Establishing Credentials

Before any party can publish data within a UDDI-enabled server, credentials and permission to publish must be supplied with the individual operator. Generally, you will only need to interact with one UDDI-enabled server because all data published at any UDDI-enabled server are replicated automatically to all other such servers. Establishing publishing credentials involves providing some verifiable identification information, contact information, and establishing security credentials with the individual server. The specifics of these establishing credentials is server-dependent, and all valid UDDI-enabled servers provide a Web-based user interface through which you can establish an identity and secure permission to publish data.

Every registry implementation that adheres to these specifications establishes its own mechanism for token generation and authentication. The only requirement placed on token generation for use with the publisher's API is that the tokens themselves must be valid string text that can be placed within the authInfo XML element. Given that binary-to-string translations are well-understood and in common use, this requirement will not introduce hardships.

Authentication tokens are not required to be valid except at the UDDI-enabled server or implementation from which they originated. These tokens need only have meaning at a single UDDI-enabled server or implementation, and should not be expected to work across sites.

#### 15.10.4.3. Generating Authentication Tokens

Many implementations are expected to require a login step. The get_authToken message is provided to accommodate implementations that desire a login step. Security schemes based on exchanging User ID and password credentials fall into this category. For implementations that desire this kind of security, the get_authToken API is provided as a means of generating a temporary authentication token.

Certificate-based authentication and similar security mechanisms do not require this additional step of logging in. Instead, they can pass compatible authentication token information such as a certificate value within the authInfo element provided on each of the publisher's API messages. If certificate-based authentication or similar security is employed the use of the get_authToken and discard_authToken messages is optional.

### 15.10.5. UDDI API Calls

This section describes the Virtuoso UDDI-related messages. These messages are divided into APIs for authentication, inquiry, and publication.

#### 15.10.5.1. Authorization API

Obtain authentication token.

Retrieve an abbreviated list of all businessEntity keys.

Inform a UDDI server that the authentication token can be discarded.

#### 15.10.5.2. Inquiry API Functions

The inquiry API messages find_binding, find_business, find_service, and find_tModel all accept an optional element named findQualifiers. This argument provides a means to allow the caller to override default search behaviors.

The messages in this section represent inquiries that anyone can make of any UDDI-enabled server 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-enabled server or 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_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 a one or more businesses. 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 date. Returns a serviceDetail message.
- get_tModelDetail: Used to get full details for a given set of registered tModel data. Returns a tModelDetail message.

Retrieves matching bindings

Retrieves a businessList message matching supplied criteria.

Retrieves serviceList message matching search criteria

locate list of tModel entries matching supplied criteria

Request run-time bindingTemplate location information.

returns complete businessEntity information for one or more specified businessEntities

Returns extended businessEntity information for one or more specified businessEntities.

request full information about a known businessService structure

Request full information about a known tModel structure.

#### 15.10.5.3. Publishing API Functions

The messages in this section represent inquiries that require authenticated access to an operator site. Each business should initially select one UDDI-enabled server to host their information. Once chosen, information can only be updated at the site originally selected.

The messages defined in this section all behave synchronously and are only callable via HTTP-POST. HTTPS is used exclusively for all the calls defined in this publisher's API.

- save_binding: Used to register new bindingTemplate information or update existing bindingTemplate information. Use this to control information about technical capabilities exposed by a registered business.
- save_business: Used to register new businessEntity information or update existing businessEntity information. Use this to control the overall information about the entire business. Of all the save messages, this one has the broadest effect.
- save_service: Used to register or update complete information about a businessService exposed by a specified businessEntity.
- save_tModel: Used to register or update complete information about a tModel.
- delete_binding: Used to remove an existing bindingTemplate from the bindingTemplates collection that is part of a specified businessService structure.
- delete_business: Used to delete registered businessEntity information from the registry.
- delete_service: Used to delete an existing businessService from the businessServices collection that is part of a specified businessEntity.
- delete_tModel: Used to delete registered information about a tModel. If there are any references to a tModel when this call is made, the tModel will be marked deleted instead of being physically removed.

save or update a complete bindingTemplate structure

Save or update information about a complete businessEntity structure.

Adds or updates one or more businessService structures.

Adds or updates one or more tModel structures.

Causes one or more bindingTemplate structures to be deleted.

Remove one or more businessEntity structures.

Remove one or more businessService structures.

Remove or retire one or more tModel structures.

### 15.10.6. Examples

Generic Find

Finds all registry entries for names beginning with 'M':

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <name>M</name>
    </find_business>
    </Body>
    </Envelope>');

Find By Name 1

Find by name with sort options by name and date, both ascending:

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <findQualifiers>
    <findQualifier>sortByNameAsc</findQualifier>
    <findQualifier>sortByDateAsc</findQualifier>
    </findQualifiers>
    <name></name>
    </find_business>
    </Body>
    </Envelope>');

Find By Name 2

Find by name, sorted by name descending and date ascending:

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <findQualifiers>
    <findQualifier>sortByNameDesc</findQualifier>
    <findQualifier>sortByDateAsc</findQualifier>
    </findQualifiers>
    <name></name>
    </find_business>
    </Body>
    </Envelope>');

Find By Name 3

Find by exact name match, case-sensitive, and sorted by name and date ascending:

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <findQualifiers>
    <findQualifier>exactNameMatch</findQualifier>
    <findQualifier>caseSensitiveMatch</findQualifier>
    <findQualifier>sortByNameAsc</findQualifier>
    <findQualifier>sortByDateAsc</findQualifier>
    </findQualifiers>
    <name>Microsoft Corporation</name>
    </find_business>
    </Body>
    </Envelope>');

Find By identifierBag Element 'DUNS':

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <findQualifiers>
    <findQualifier>exactNameMatch</findQualifier>
    <findQualifier>caseSensitiveMatch</findQualifier>
    <findQualifier>sortByNameAsc</findQualifier>
    <findQualifier>sortByDateAsc</findQualifier>
    </findQualifiers>
    <identifierBag>
    <keyedReference keyName="D-U-N-S" keyValue="08-146-6849"
      tModelKey="UUID:8609C81E-EE1F-4D5A-B202-3EB13AD01823"/>
    </identifierBag>
    </find_business>
    </Body>
    </Envelope>');

Find by tModel

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <findQualifiers>
    <findQualifier>exactNameMatch</findQualifier>
    <findQualifier>caseSensitiveMatch</findQualifier>
    <findQualifier>sortByNameAsc</findQualifier>
    <findQualifier>sortByDateAsc</findQualifier>
    </findQualifiers>
    <tModelBag>
    <tModelKey>UUID:68DE9E80-AD09-469D-8A37-088422BFBC36</tModelKey>
    </tModelBag>
    </find_business>
    </Body>
    </Envelope>');

Find by discovery URL

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <findQualifiers>
    <findQualifier>exactNameMatch</findQualifier>
    <findQualifier>caseSensitiveMatch</findQualifier>
    <findQualifier>sortByNameAsc</findQualifier>
    <findQualifier>sortByDateAsc</findQualifier>
    </findQualifiers>
    <discoveryURLs>
    <discoveryURL>
    http://uddi.microsoft.com/discovery?businessKey=D94B25A4-BD6D-4426-AEAC-1087DCC21421
    </discoveryURL>
    </discoveryURLs>
    </find_business>
    </Body>
    </Envelope>');

Get authentication token

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <get_authToken xmlns="urn:uddi-org:api" generic="1.0">
    <userID>dav</userID>
    <cred>dav</cred>
    </get_authToken>
    </Body>
    </Envelope>');

Discard Authentication Token

    select http_get ('http://localhost:6666/SOAP', null, 'POST',
      'Content-Type: text/xml\r\nSOAPAction: ""',
      '<?xml version="1.0" encoding="UTF-8"?>
    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Body>
    <discard_authToken xmlns="urn:uddi-org:api" generic="1.0">
    <authInfo>71255ffc5b0a22b4699bfcee74cba97f</authInfo>
    </discard_authToken>
    </Body>
    </Envelope>');

See Also:

UDDI System Tables

Previous SyncML | Chapter Contents | Next Exposing Persistent Stored Modules as Web Services