[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [regrep] Re: REST Proposal, Latest Version
Sorry, the copy I sent out earlier has a problem with one of the hyperlinks. Here is a fixed version. -MattTitle: OASIS ebXML Registry REST Interface Proposal
Proposal 0.5, 6 August 2002
Copyright © 2002 The Organization for the Advancement of Structured Information Standards [OASIS] Table of Contents
AppendixesThe following motivations drive this proposal:
This proposal depends upon the following external artifacts:
This section defines the REST Interface to ebXML Registry 3.0+. This section describes briefly some use cases which this proposal addresses. 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. 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. 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: http://www.mysite.com/restprocessor?object=Catalog&method=listItems 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. 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. 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:
NOTE: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. This section defines URI parameters that are used by the REST Interface. Table 1. URI Parameters
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. In order to facilitate simple, ID based access to a RegistryObject, two new methods will be added to QueryManager:
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¶m-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 />
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. The REST Interface to LifecycleManager consists of the interface name "LifecycleManager", and all methods defined in that interface including:
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. 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. 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. NoticesCopyright © 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. This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 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 RightsFor 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
Non-Normative[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. |
On Wednesday, August 7, 2002, at 11:12 , Matthew MacKenzie wrote: > Team, > > Attached is the latest version of the REST proposal. All comments to > date have been considered and where appropriate addressed in the > document. > > 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. > > Regards, > > Matthew MacKenzie > Chief Software Architect > XML Global Technologies, Inc. > p: +1 (604) 717-1100 x107 > m: +1 (604) 781-4721 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC