OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

regrep message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: [regrep] REST Proposal, Latest Version


Attached is the latest version of the REST proposal.  All comments to 
date have been considered and where appropriate addressed in the 

You will notice the security and exception handling sections are very 
brief, and don't say too much.  This is very much intentional, as the 
REST interface endeavors only to add a simple HTTP interface to 
ebRegRrep.  Security and Exception handling should, in my opinion, be a 
function of the underlying registry so that there is a clean abstraction 
between transport and registry functions.

Particular thanks goes to Farrukh, Nikola and Joel (Munter) for their 
help in reviewing the document.


Matthew MacKenzie
Chief Software Architect
XML Global Technologies, Inc.
p: +1 (604) 717-1100 x107
m: +1 (604) 781-4721

Title: OASIS ebXML Registry REST Interface Proposal

OASIS ebXML Registry REST Interface Proposal

Proposal 0.5, 6 August 2002

Document identifier:

pl-REST-regrep3-0.5 (XML, HTML, PDF)


Matthew MacKenzie, XML Global Technologies, Inc. <Matt@XMLGlobal.Com>


Farrukh Najmi, Sun Microsystems <Farrukh.Najmi@Sun.Com>
Nikola Stojanovic <Nikola.Stojanovic@acm.org>


This document proposes a new feature of the OASIS ebXML Registry targeted for version 3.0. REST, or REpresentational State Transfer, is an architectural style of exposing applications via the web or other URI centric transports. The key tenet of the style is the use of URIs, or in the case of http, URL’s to define the actions and parameters of an interfaces invocation. REST also tends to be biased toward the http GET action, as opposed to POST or PUT, mainly because POST/PUT based applications tend to hide all of the request information in the content which is POSTed, thereby devaluing the location specificity of the URI.

This document proposes a hybrid REST approach, with POST being used where GET is not practical. When the invocation parameters are too numerous or complicated, using POST is necessary, however, this is a hybrid approach because we try to still keep the URI somewhat meaningful even when performing a POST.


This note describes the initial proposal for the REST Interface work item for OASIS ebXML Registry V3.0. It is expected that the Federated Registries sub-team of the OASIS ebXML Registry TC will improve upon this initial proposal and then submit it for consideration by ebXML Registry TC at large.

If you are on the <regrep-cooperating@lists.oasis-open.org> list for committee members, send comments there. If you are not on that list, subscribe to the <regrep-cooperating@lists.oasis-open.org> list and send comments there. To subscribe, send an email message to <regrep-cooperating-request@lists.oasis-open.org> with the word "subscribe" as the body of the message.

1. Motivation

The following motivations drive this proposal:

  1. Provide a mechanism to be used in conjunction with the ObjectRef object which is a proposed addition to the registry information model, version 3.0, for retrieving or importing objects which are physically located in another registry or URL addressable location. This mechanism mustn’t hamper a registry’s ability to manage large numbers of ObjectRefs by being too "heavy" in processing or network demands.

  2. Enable distribution of registry content.

  3. Provide another integration route for developers who are integrating the use of ebXML Registry into their offerings.

  4. Incorporate the functionality described in an earlier proposal/best practice document for ebXML Registry v2, entitled "URL Interface to OASIS ebXML Registry".

2. External Dependencies

This proposal depends upon the following external artifacts:

  • HTTP 1.1. The REST interface must be implemented upon an implementation of HTTP 1.1.

3. REST Interface

This section defines the REST Interface to ebXML Registry 3.0+.

3.1. Use Cases

This section describes briefly some use cases which this proposal addresses.

3.1.1. Use Case: Inter-Registry Object References

A non-ebXML registry such as UDDI wishes to reference and access the repository items in the repository of an ebXML Registry. For example a bindingTemplate may reference a WSDL document that is stored in an ebXML Registry's repository.

3.1.2. Use Case: Hyperlinking to Registry Entries/Objects

The author of a web page wishes to include a hyperlink in that page which resolves to an object or entry in a ebXML Registry instance. For example, prose documentation for an XML Schema might link to the schema which is stored in an ebXML registry's repository.

3.1.3. Use Case: Lightweight Client

The developer of a hardware or software platform has a requirement which involves submitting or retrieving objects/entries to an ebXML Registry, but cannot afford the overhead of a full SOAP 1.1 or ebXML Messaging client.

3.2. What Is REST?

REST, which stands for Representational State Transfer, is an architectural style for distributed hypermedia systems. When you expose an interface to the world (or some subset thereof), you are essentially embedding method calls in the request URI. For example, if we were exposing a class named Catalog using REST, a client would send a http GET request to a URL that is formed something like the following:


The return value would be sent back to the client synchronously in a format that is appropriate for such a request, or perhaps there is a URL parameter that can be set to define the return format (XML, HTML or CSV perhaps?). REST is more of a concept than a technology, and better yet, REST is easily implemented using standard facilities found on a web server or development environment.

3.3. Definition of the REST Interface to ebXML Registry

The specification of the REST Interface for ebXML Registry is constrained to the specification of what URI parameters must be used to specify the interface, method and invocation parameters being used.

3.3.1. Minimum Exposed Interface

At the bare minimum, it is necessary to expose functionality via REST to retrieve Registry Objects with. This is required to support the Registry Federation feature of ebXML Registry 3.0.

The minumum interface that must be exposed is explained below:


Since a certain amount of interface mapping is required to expose all of the registry’s lifecycle management via REST, this document will describe how this should be done, although implementing a complete REST interface is not required by this proposal.

3.3.2. URI Parameters

This section defines URI parameters that are used by the REST Interface.

Table 1. URI Parameters

Parameter NameRequiredPurposeNotes
interfaceYESDeclares the interface or object to call methods on.Example: ObjectQueryManager
methodYESDeclares the method to be carried out on the given interface.Example: submitAdhocQueryRequest
param-<key>NODeclares named parameters to be passed into a method call.Example: param-id=888-999-8877h
var-<key>NODeclares variables.Example: var-maxeffort=2m

4. QueryManager REST Interface

The REST Interface to QueryManager consists of the interface name "QueryManager", and the one method defined in that interface, submitAdhocQueryRequest.

There are two ways to access the QueryManager via the REST interface: http GET based, and http POST based. The GET based method represents the minimum implementation of this proposal.

4.1. HTTP GET Based Access to QueryManager

In order to facilitate simple, ID based access to a RegistryObject, two new methods will be added to QueryManager:

  • getRegistryEntryByID

  • getRegistryObjectByID

To execute these requests, a URI parameter, named "id" must be used to specify the ID. The response returned will be a RegistryResponse in XML fomat. Below is a sample request and response:

Example 1. GET Request

GET /rest?interface=QueryManager&method=getRegistryEntryByID&param-id=urn:uuid:8788-hhghh-ttttt HTTP/1.0   

Example 2. GET Response

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 555
<?xml version="1.0"?>
<RegistryResponse />

4.2. HTTP POST Based Access to QueryManager

The submitAdhocQueryRequest method takes a properly formed AdhocQueryRequest, and returns a RegistryResponse in XML format. In the REST interface, the AdhocQueryRequest is delivered using the http POST action. Below is a sample request and response:

Example 3. POST Request

POST /rest?interface=QueryManager&method=submitAdhocQueryRequest HTTP/1.0
User-Agent: Foo-ebXML/1.0
Host: www.registryserver.com
Content-Type: text/xml
Content-Length: 555
<?xml version="1.0"?>
<AdhocQueryRequest />

Example 4. POST Response

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 555
<?xml version="1.0"?>
<RegistryResponse />   

Please refer to the most current ebXML RS and RIM specifications for details on how to for the requests and responses mentioned above.

5. LifecycleManager REST Interface

The REST Interface to LifecycleManager consists of the interface name "LifecycleManager", and all methods defined in that interface including:

  • approveObjects

  • deprecateObjects

  • removeObjects

  • submitObjects

  • updateObjects

  • addSlots

  • removeSlots

The requests for each method must be delivered using HTTP POST in XML format. The return value will always be a RegistryResponse in XML format. Below is a sample request and response:

Example 5. Request

POST /rest?interface=LifecycleManager&method=approveObjects HTTP/1.0
User-Agent: Foo-ebXML/1.0
Host: www.registryserver.com
Content-Type: text/xml
Content-Length: 555
<?xml version="1.0"?>
<ApproveObjectsRequest />


Example 6. Response

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 555
<?xml version="1.0"?>
<RegistryResponse />

Please refer to the most current ebXML RS and RIM specifications for details on how to for the requests and responses mentioned above.

6. Security Considerations

The REST interface supports the same mechanisms for data integrity and source integrity as are mentioned in the Registry Services specification. Authentication may be performed by the registry on a per message basis by verifying any digital signatures present, as well as at the HTTP transport level using Basic or Digest authentication.

7. Exception Handling

Since the REST interface is merely an interface to various registry objects, exception handling will take the same form as they do over other registry transports. Errors encountered at the transport level such as a malformed request will be handled using HTTP 1.1's error reporting guidelines.

A. Notices

Copyright © The Organization for the Advancement of Structured Information Standards [OASIS] 2001, 2002. All Rights Reserved.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.


OASIS has been notified of intellectual property rights claimed in regard to some or all of the contents of this specification. For more information consult the online list of claimed rights.

B. Intellectual Property Rights

For information on wether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the {technical-committee} web page (http://www.oasis-open.org/committees/regrep)

C. Revision History

Revision 0.56 August 2002mm
Incorporated comments, added security and exception handling.
Revision 0.48 July 2002mm
Converted document to Docbook XML from MS Word.
Revision 0.33 July 2002mm
Incorporated changes from Farrukh.
Revision 0.21 July 2002mm
First public draft.



[RESTThesis] Roy Thomas Fielding. Architectural Styles and the Design of Network-based Software Architectures . Doctoral Dissertation, University of California, Irvine. 2000.

[URIInterface] Matthew MacKenzie. URL Interface to OASIS ebXML Registry . Best Practices. 2002.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC