Versioning

Overview

It is worthwhile reading the entire Memento specification to become acquainted with the Memento terminology (such as Original Resource, a Memento resource, Timemap, Timegate) and various interaction patterns, but the most relevant sections of the Memento specification to Fedora are section 4.1.1 and its relevant parent sections.  Section 4.1.1 presents the HTTP/Memento interaction pattern implemented in Fedora.  Also, familiarizing yourself with the Versioning section (Section 4) of the Fedora API Specification will be helpful to understanding concepts and terminology (LDPRv, LDPCv, LDPRm).

Terminology

A mapping of terminology between the Memento definition of resources and those used in the Fedora API Specification is helpful:

Memento Original Resource = Fedora API LDPRv

This is the resource of which versions can be made.  Also called the versionable resource.

Memento Timegate = Fedora API LDPRv

A Memento Timegate is a resource to which a request can be made for a relevant versioned resource (LDPRm, see below).  The Memento specification allows the Original Resource and the Timegate to be the same resource.  Fedora has taken advantage of this efficiency and uses the LDPRv as the Memento Timegate in addition to the LDPRv being the Memento Original Resource.

Memento “Memento” Resource = Fedora API LDPRm

This is the versioned resource.  It is usually a snapshot of a LDPRv (a.k.a Memento Original Resource).

Memento Timemap = Fedora API LDPCv

This is a LDP container (hence the ‘C’) that aggregates versioned resources (LDPRm resources).  A POST request to this resource will result in a new LDPRm (Memento Resource).

RESTful API - Versioning

Memento Datetime Negotiation Algorithm

The date algorithm Fedora uses to determine which LDPRm should be returned to a TimeGate request, as indicated by the value of the Accept-Datetime header, is as follows: 

• Any Accept-Datetime value that is earlier than the first/oldest Memento will return a reference to the first/oldest Memento. 
• Any Accept-Datetime value that is later than a specific Memento’s timestamp but earlier than another Memento’s timestamp will return the older Memento. 
• An Accept-Datetime value that matches a stored Memento datetime value perfectly will return the Memento preserved at that timestamp.
• An Accept-Datetime value that is later than the last Memento will return a reference to the last/youngest Memento.

Fedora follows Memento Datetime negotiation pattern 1.1 as described in section 4.1.1 of the Memento specification, in which the Original Resource Acts as its own TimeGate (URI-R=URI-G; 302-Style Negotiation; Distinct URI-M).

Note bene

Fedora automatically versions all changes to all resources by default.  This can be changed by setting the fcrepo.autoversioning.enabled  property to false. You can find more information on how to configure properties on the Properties page.

Memento has a one second granularity, because of this there are some things to consider for both automatic and manual versioning.

• Manual versioning
  • You are unable to create two versions within a single second.
• Autoversioning
  • If more than one versions are automatically generated in a single second then you can only access the last version via the Fedora HTTP API. You can see all versions by browsing the OCFL storage on disk.

The Memento specification strongly suggests clients initiate negotiation with a HEAD request.  This is largely because all interaction with Memento operates within HTTP Headers.  They must be examined closely.  Headers are the only way to learn that a resource is a LDPRv (a Memento Original Resource and a Memento Timegate) or a LDPRm (a Memento). 

The subject of the resource returned from a GET response to a LDPRm (a Memento) will the same as the subject of the “parent” resource (the Memento Original Resource or LDPR).  This is one of the reasons it is imperative to inspect the headers of these responses as it may only be possible to determine that the resource is a LDPRm from the response headers.

Fedora will emit messages after the creation of a LDPRv resource (Memento Original Resource), the creation of LDPRm resources (Mementos), and the deletion of LDPCv resources (Memento Timemaps) and LDPRm resources.  These messages provide no hint that they pertain to versioning.  If software acts on these messages, that software should perform a HEAD request on the resource and inspect the headers to determine if the resource is related to Fedora versioning, and if further action is warranted.