Overview
| Excerpt |
|---|
| Within Fedora, snapshots of the current state of a resource may be saved into the version history. The RDF for historic versions may be browsed and old non-RDF content may be downloaded. Furthermore, an object may be reverted to the state that it existed in a historic version. |
Creating versions
When you wish to save a snapshot of the current version of a node to the version history you can use the REST API. The version label will be automatically generated based on the current timestamp (with second granularity).
...
| title | Click to expand the full REST API Documentation... |
|---|
Versioning in Fedora implements the Memento protocol. Its formal name is HTTP Framework for Time-based Access to Resource States – Memento. This document focuses exclusively on how the Fedora software implemented the Memento software and best practices when using Fedora Versioning. |
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 theHTTP/Memento interaction pattern implemented in Fedora. Also, familiarizing yourself with the Versioning section (Section 4 - https://fcrepo.github.io/fcrepo-specification/#resource-versioning) 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
| excerpt-include | ||||
|---|---|---|---|---|
|
| Note | ||
|---|---|---|
| ||
| If a resource has a version with a given timestamp, you may not create another version with that timestamp. If you later delete a that version, you may then create a new version with that timestamp. |
...
Version creation can be a relatively costly operation. With the ability to create versions whenever you wish, you can develop workflows that maximize the utility of this feature.
Possible strategies include:
- For batch operations, only create version checkpoints once nodes have been ingested, verified and tested.
- For small (but high-level) data such as the descriptive metadata created by subject experts, set a versioning policy to store every modification, thereby capturing the entirety of the curatorial endeavor.
- Create snapshot versions that correspond to released versions of content (i.e., version X of a shared dataset, controlled vocabulary or collection)
Fedora Versioning/Memento Date 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 result in 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.
Note bene
Fedora does not automatically initiate versioning for all resources. The client MUST initiate versioning by invoking a special Link header at the time a resource is created. See ?????
It is possible to convert a LDPR into a LDPRv after the LDPR exists, but this process effectively forces the client to recreate the existing resource as a new resource by performing a GET on the existing resource and then resubmitting the resource, via a PUT, with the proper Link header.
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.
LDPRm resources should generally be created by issuing a simple POST request to the LDPCv (Memento Timemap) resource, but it is technically possibly to issue a POST request with a message body, which will be stored as a LDPRm (Memento), and a timestamp, which will be used as the Memento Datetime. This functionality – providing the resource to be stored as a versioned resource - exists to address the need to be able to Import data to Fedora as a part of a migration. It is inadvisable to create LDRPm resources with POST and a message body without specific need to take advantage of this feature.
Viewing old Versions
From the HTML view (or by issuing HTTP GET methods via an HTTP client program) you can get the version history of a node by appending "/fcr:versions" to it's base URL. Each version will be listed, with the version label as the title.
Previewing historic properties
By clicking on the box for a version you can expand and collapse a view of the version properties.
Navigating to the full view of an historic version
By clicking on the label of a version in the version listing you will be taken to the stored version of that resource. Because it's part of the historic record, you cannot edit it, but you can view it, download non RDF-content or revert the resource or subraph to that version.
Reverting to a previous version
If you wish to restore an object to a previous version, you must do so using the RESTful HTTP API - Versioning, or even the HTML view. In the HTML view of a historic version, a button "Revert to this Version" exists, that when clicked restores the object to the version viewed.
| Info |
|---|
When restoring an old version, two operations occur:
|
Deleting a previous version
If you wish to remove historic version snapshots you may do so either using the REST API or the HTML view of the historic version.