Resource Revision Histories Additional Service

This specification outlines the revision history capability provided by the storage services of an Open Services for Lifecycle Collaboration provider. The revision history is not intended as a complete Configuration Management revision service, rather it is intended to provide an audit trail of all changes made to individual resources.

Motivation

The revision history service allows client applications to guarantee to users that at any point they can review previous changes and associate these changes with a user. For example, a user may encounter an error where the resource they are attempting to save to the server clashes with an update made to that resource by another user. With a revision history the user can then see who and when the change took place. The fact that each revision of a resource also has a unique URI means that applications that care about specific revisions of resources can link to either the current or the specific revision of a resource.

A storage resource's revision history begins when a resource with a given URI is first created. This creates an initial revision resource which shows up in the revision history as the current revision. Each time the storage resource is updated, a new revision resource is created and added to the revision history. The revision resource captures the contents of the storage resource as a result of the update. Contiguous revisions are bi-directionally linked with predecessor and successor links that are included in the revision history.

Specification

The revision history service provides two specific capabilities, the ability to get a list of all revisions for a particular resource (the revision feed) and to retrieve the representation of a specific revision of a resource (revision-specific resource).

Revision Feed

The revision feed is accessed by simply adding the single query parameter "?revisions" (note the plural) to the resource URI. An example of a revision feed follows.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en-us" >
  <title>Resource History</title>
  <subtitle>History for /jazz/resources/search/res-1.txt</subtitle>
  <link rel="self" href="/jazz/resources/search/res-1.txt" />
  <id>/jazz/resources/search/res-1.txt</id>
  <updated>2008-05-19 11:42:16.162238</updated>
  <generator>Drake Resource Services</generator>  
  <entry>
    <title>/search/res-1.txt?revision=1</title>
    <link rel="alternate" type="text/plain" 
      href="/jazz/resources/search/res-1.txt?revision=1"></link>
    <id>/jazz/resources/search/res-1.txt?revision=1</id>
    <updated>2008-05-19 11:42:16.162238</updated>
    <author><name>simon</name></author>
    <content type="text/plain" 
      src="/jazz/resources/search/res-1.txt?revision=1"/>
    <summary type="text">Revised on Mon, 19 May 2008 11:42:16 +1900, 
                         by simon</summary>
  </entry>
</feed>

Method	URL	Comments
`GET/HEAD`	`{revision-uri}?revisions`	Returns an Atom Feed with one entry per revision of the resource, entries are sorted in descending order of the last-modified date. The server will respond with a 200 (OK) status code on success, or one of the following errors: 401 (unauthorized), 403 (forbidden), 404 (not found), 500 (server error) or 503 (service unavailable).
`POST`	`{revision-uri}?revisions`	Not permitted - returns 405 (Method not allowed).
`PUT`	`{revision-uri}?revisions`	Not permitted - returns 405 (Method not allowed).
`DELETE`	`{revision-uri}?revisions`	Not permitted - returns 405 (Method not allowed).

Links in Revision Entries

To allow clients to navigate the resource history the feed will include a pair of specific links to each atom:entry to denote the relationship between entries. Note that no client may rely on interpreting the value of a revision identifier and implying an order from them and so a means for identifying the precise relationship is needed. These two links have values for the atom:rel attribute of:

http://example.org/xmlns/openservices/v0.6#successor - a link to the revision that follows the current revision.
http://example.org/xmlns/openservices/v0.6#predecessor - a link to the revision that precedes the current revision.

This implies that the very first revision of a resource (the very first resource at this URL or a newly created resource after an archived resource) has no predecessor link, that an entry denoting an archived resource and the last revision of a resource has no successor link. The following diagram illustrates the link relationships.

Revision-Specific Resource

A revision-specific resource is retrieved in a similar manner, using a query parameter "?revision={id}". The scheme any server uses to create an identifier for a specific resource is not defined by these specifications; a server is at liberty to assign any reasonable scheme that provides a unique identifier to each resource revision.

Method	URL	Comments
`GET/HEAD`	`{revision-uri}?revision={id}`	Returns the resource representation as of the specified revision. The server will respond with a 200 (OK) status code on success, or one of the following errors: 401 (unauthorized), 403 (forbidden), 404 (not found), 500 (server error) or 503 (service unavailable).
`POST`	`{revision-uri}?revision={id}`	Not permitted - returns 405 (Method not allowed).
`PUT`	`{revision-uri}?revision={id}`	Not permitted - returns 405 (Method not allowed).
`DELETE`	`{revision-uri}?revision={id}`	Not permitted - returns 405 (Method not allowed).

Notes:

A server is at liberty to set specific cache expiration and cache control headers for a revision-specific resource as it cannot change in the future.


User ID:
Password: