Author: Matthew J. Dovey, 28 October 2004
C.R.U.D.
There are a number of WebServices or WebService profiles implementing “C.R.U.D” (Create, Retrieve, Update and Delete) APIs. Currently this list includes REST, ATOM, WS-Transfer and WSRF. This document outlines how SRW Update can be mapped onto these WebServices.
These specifications all work on the same principle. They all have a means of identifying the resource, a means of indicating the operation to be performed on that resource (Create, Retrieve, Update or Delete), and the information required to perform that operation (typically as an arbitrary XML document). Where they differ is how the id and operation are represented. In terms of the Record Update specification, the basic schema would remain unchanged for transferring data but without the ucp:operation and ucp:recordIdentifier elements. The operation and id would be encoded according to the specific profile in use.
REST
REST is currently an alternative technology to SOAP for WebServices. Whilst it has a large following it is not an official standard. REST maps the CRUD operations onto the HTTP verbs (Create = HTTP POST, Retrieve = HTTP GET, Update = HTTP PUT, Delete = HTTP DELETE), whilst the id of the resource is encapsulated within the URL.
Mapping to SRW Update
The HTTP request would use the appropriate HTTP verb to indicate the ucp:operation (HTTP POST for info:srw/operation/1/create etc.). The ucp:recordIdentifier would be encoded in the URL – e.g. the service could be at the endpoint http://server/service/ but the URL used for the Update operation would be http://server/server/recordid. The ucp:request structure (without ucp:operation and ucp:recordIdentifier) would be used for requests. Where appropriate ucp:response would be used in the responses.
Issues
- REST limits the protocol to using HTTP.
- It isn’t clear that all operations (e.g. PUT and DELETE) should return any data, i.e. could return a ucp:response [Authors note: I’ve looked through the W3C HTTP 1.1 spec and it says that the presence of request and response bodies depend on the operation but I can’t find where it says which operations permit which request/response bodies!]
- To be truely REST, HTTP error codes should be used rather than srw:diagnostics
- Some recordIdentifiers might be difficult to encode as a URL
ATOM
ATOM was developed as a means of maintaining Blogs – however since a Blog entry can be any XML document it can be used to maintaining any XML data source. ATOM has been submitted for IETF consideration. ATOM has both a SOAP and REST API. In REST, you determine the create-entry URL via an introspection URL (akin to explain). You would send this the following message using HTTP POST:
POST /myblog/atom.cgi/edit HTTP/1.1
Host: example.com
Content-Type: application/x.atom+xml
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#">
<author>
<title>My Entry Title</title>
<created>2003-11-17T12:29:29Z</created>
<content type="application/xhtml+xml"
xml:lang="en">
<div
xmlns="http://www.w3.org/1999/xhtml">
<p>Hello,
<em>weblog</em> world!</p>
<p>This is my third post
<strong>ever</strong>!</p>
</div>
</content>
</entry>
This would return a URL acting as the id for the new entry. You could use this URL in further HTTP POST messages for updating. The SOAP implementation uses the same entry XML structure (although with an addition field for the recordId) and uses SOAP operations for PUT, POST, GET and DELETE. The response can contain a similar entry structure.
Mapping to SRW Update
The ucp:request structure (without ucp:operation or ucp:recordIdentifer) could be passed as within the content element of the ATOM entry element in the request. The ucp:operation would be mapped to the appropriate REST or SOAP operation. In the SOAP version of ATOM, the ucp:response can be returned in the content element of the entry element in the response. It is less clear how to do this in the REST implementation.
Issues
- The REST implementation has the same issues as layering Record Update over pure REST – no response structure for some operations.
- Some metadata can be transferred during the record update and creation operations as sub-elements of the entry element (e.g. author, title and date)
WS-Transfer
WS-Transfer is a proposal from Microsoft, Computer Associates, BEA and others for a means of using WS-Addressing for a CRUD based WebService. It currently is not an official standard. In WS-Transfer the operation and id are carried within the SOAP:Header as WS-Addressing elements, e.g.
<s:Envelope ...>
<s:Header ...>
<wsa:Action> http://schemas.xmlsoap.org/ws/2004/09/transfer/Get
</wsa:Action>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ... />
</s:Envelope>
Mapping to SRW Update
ucp:operation would be encoded as an appropriate wsa:Action in the SOAP header (using one of the URIs: http://schemas.xmlsoap.org/ws/2004/09/transfer/Get, http://schemas.xmlsoap.org/ws/2004/09/transfer/Put, http://schemas.xmlsoap.org/ws/2004/09/transfer/Delete, http://schemas.xmlsoap.org/ws/2004/09/transfer/Create). The ucp:recordIdentifer would be encoded as wsa:To (as a URI). The ucp:request would be passed in the SOAP:Body. For the response wsa:Action in the header would contain the appropriate URI from the list (http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse, etc), wsa:RelatesTo the recordIdentifier, and the SOAP:Body the ucp:response. The exception to this is Create, where the wsa:To and wsa:RelatesTo should be to a “factory” which can create resources (e.g. a URI reference to a database), and the SOAP:Body must contain a wxf:ResourceCreated element containing the URI reference to the newly created resource, as well as the ucp:request.
Issues
- Some recordIdentifiers might be difficult to encode as a URL
- Restricted to SOAP
WSRF
WS Resource Framework is a family of standards for creating, maintaining and interacting with stateful remote resources. Within this context a record, catalogue or database can be regarded as a remote stateful resource. The OGSA-DAI project for example is looking into migrating to WSRF for maintaining heterogeneous databases. The resource identifier is carried in the SOAP:Header using was:To as for WS-Transfer. WS-Resource Properties defines a WebService with SOAP Operations GetResourceProperties and SetResourceProperties for editing one or more “properties” of the resource. The available properties and the XML schemas are given as annotations in the WSDL of the WebService description.
Mapping to SRW Update
the recordVersion, and the different record schemas (for both the record and the record metadata) that can be accepted would be encoded in the WSDL as resource properties. GetResourceProperties and SetResourceProperties would be used to maintain these “properties”. WS Resource Lifetime WebService operations would be used to create and destroy records. Diagnostics would be returned in appropriate SOAP:Faults.
Issues
- Major refactoring of record update to adopt WSRF properly
- Would ideally require WSRF complaint software stack
- Diagnostics would need to be recast as decendent SOAP faults of WS-BaseFaults