Old Release

This documentation covers an old version of Fedora. Looking for another version? See all documentation.

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Overview

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).



Versioning in Fedora is composed of three specific types of resources - a versionable resource (a LDPRv), a versions container (a LDPCv), and the actual versioned resource (a LDPRm)- and a variety of strategies to interact with these resources.  Each type of resource and the HTTP methods that can be used on them are discussed below.


Working with a versionable resource (a LDPRv)


A versionable resource is a type of (regular) resource - see RESTful HTTP API - Containers - but it is created by invoking a specific Link header and the GET method has an additional interaction model beyond the GET scenarios when interacting with non-versioned resources.  All of the headers and methods for regular resources are applicable to a versionable resource.

A resource can be declared versionable when it is created originally.  This is achieved by including the following link header to your PUT or POST commands when creating the resource.  When a versionable resource is created, the versions container will be created at the same time.

Link: <http://mementoweb.org/ns#OriginalResource>; rel="type"


Request URI: /path/to/resource

Methods: GET, PUT, POST

GET Retrieve the versioned resource from a specific point in time.

For more details about Fedora's datetime negotiation behaviors, see Memento Datetime Negotiation Algorithm.

Request Headers:

ACCEPT-datetime  An RFC-1123 Date. (E.g. "Wed, 30 May 2018 23:02:44 GMT")

Example:

curl -H "Accept: text/turtle" -H "Accept-Datetime: Wed, 29 Aug 2018 15:47:50 GMT" http://localhost:8080/rest/path/to/resource

Response:

HTTP/1.1 302 Found
Date: Wed, 29 Aug 2018 22:09:28 GMT
Set-Cookie: JSESSIONID=hrj5jm80kdjdw9attrozpy19;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Tue, 28-Aug-2018 22:09:28 GMT
Link: <http://www.w3.org/ns/ldp#Resource>;rel="type"
Link: <http://www.w3.org/ns/ldp#Container>;rel="type"
Link: <http://www.w3.org/ns/ldp#BasicContainer>;rel="type"
Link: <http://localhost:8080/static/constraints/ContainerConstraints.rdf>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Link: <http://localhost:8080/rest/path/to/resource6>; rel="timegate"
Link: <http://localhost:8080/rest/path/to/resource>; rel="original"
Link: <http://localhost:8080/rest/path/to/resource/fcr:versions>; rel="timemap"
Link: <http://mementoweb.org/ns#OriginalResource>; rel="type"
Link: <http://mementoweb.org/ns#TimeGate>; rel="type"
Accept-Patch: application/sparql-update
Accept-Post: text/turtle,text/rdf+n3,text/n3,application/rdf+xml,application/n-triples,application/ld+json
Allow: MOVE,COPY,DELETE,POST,HEAD,GET,PUT,PATCH,OPTIONS
Link: <http://localhost:8080/rest/path/to/resource/fcr:acl>; rel="acl"
Preference-Applied: return=representation
Vary: Prefer
Vary: Accept
Vary: Range
Vary: Accept-Encoding
Vary: Accept-Language
Vary: Accept-Datetime
Location: http://localhost:8080/rest/path/to/resource/fcr:versions/20180829154750
Content-Length: 0
Server: Jetty(9.3.1.v20150714)

Status:

200 302 Found

400 Bad Request: Accept-Datetime header not properly formatted per RFC-1123

406 Unacceptable: No appropriate versioned resource found for the supplied Accept-Datetime value



Examples: 

#PUT 
curl -X PUT -H "Link: <http://mementoweb.org/ns#OriginalResource>; rel=\"type\"" http://localhost:8080/rest/path/to/resource


#POST 
curl -X POST -H "Link: <http://mementoweb.org/ns#OriginalResource>; rel=\"type\"" -H "Slug: resource" http://localhost:8080/rest/path/to


Working with a versions container (a LDPCv)


Request URI: /path/to/resource/fcr:versions

Methods: GET, POST, DELETE

GET Get a list of the available versions of an object

Request Headers:

ACCEPT  application/ld+json, application/link-format, application/n-triples, application/rdf+xml, application/x-turtle, application/xhtml+xml, application/xml, text/html, text/n3, text/plain, text/rdf+n3, text/turtle

Example:

curl -H "Accept: text/turtle" http://localhost:8080/rest/path/to/resource/fcr:versions

Response:

Status: HTTP/1.1 200 OK


Headers:
	 ETag: W/"671df2a47622331ffb6b70b6156526a67e5ab760"
	 Last-Modified: Wed, 30 May 2018 21:03:54 GMT
	 Link: <http://www.w3.org/ns/ldp#Resource>;rel="type"
	 Link: <http://www.w3.org/ns/ldp#RDFSource>;rel="type"
	 Link: <http://localhost:8080/rest/path/to/resource/fcr:versions/fcr:acl>; rel="acl"
	 Link: <http://mementoweb.org/ns#TimeMap>; rel="type"
	 Link: <http://localhost:8080/rest/path/to/resource>; rel="original"
	 Link: <http://localhost:8080/rest/path/to/resource>; rel="timegate"
	 Link: <http://localhost:8080/rest/path/to/resource/fcr:versions>; rel="timemap"
	 Vary-Post: Memento-Datetime
	 Allow: POST,HEAD,GET,OPTIONS,DELETE
	 Preference-Applied: return=representation
	 Vary: Prefer
	 Vary: Accept
	 Vary: Range
	 Vary: Accept-Encoding
	 Vary: Accept-Language
	 Content-Type: text/turtle;charset=utf-8
	 Content-Length: 1944


Body: 


@prefix memento:  <http://mementoweb.org/ns#> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix fedora:  <http://fedora.info/definitions/v4/repository#> .
@prefix ldp:  <http://www.w3.org/ns/ldp#> .

<http://localhost:8080/rest/path/to/resource/fcr:versions>
        rdf:type               fedora:TimeMap ;
        rdf:type               fedora:Resource ;
        fedora:lastModifiedBy  "bypassAdmin" ;
        fedora:createdBy       "bypassAdmin" ;
        fedora:created         "2018-05-30T21:00:48.169Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
        fedora:lastModified    "2018-05-30T21:03:54.88Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
        memento:original       <http://localhost:8080/rest/path/to/resource> ;
        rdf:type               ldp:RDFSource ;
        fedora:writable        true ;
        ldp:contains           <http://localhost:8080/rest/path/to/resource/fcr:versions/20180530210300> ;
        ldp:contains           <http://localhost:8080/rest/path/to/resource/fcr:versions/20180530210354> .

Status:

200 OK

404 Not Found: Versions container resource does not exist.


 

POST Create a new versioned resource (a new LDPRm)

Versions can by created in one of two ways, with a Memento-Datetime header and request body or with neither. If the Memento-Datetime header is omitted, the current time will be used by default and the current state of the versionable resource will be preserved.  Any specified body will be ignored.  If, however, the Memento-Datetime header is included, the versioned resource will be stored at this time marker and the request body will be stored as the versioned resource. 

Request Headers

MEMENTO-DATETIME (Optional) An RFC-1123 Date. (E.g. "Wed, 30 May 2018 23:02:44 GMT")


Example 1 (Create a new version resource 'now.'  Its state is that of the current versionable resource.):

# Create version from current state of the object 
curl -X POST http://localhost:8080/rest/path/to/resource/fcr:versions

Response:

HTTP/1.1 201 Created
Date: Wed, 29 Aug 2018 21:21:34 GMT
Set-Cookie: JSESSIONID=dmqpuv06yty7b0tf9y94z3rx;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Tue, 28-Aug-2018 21:21:34 GMT
ETag: W/"f7c04eb7e3f04c17d1fc852bef5f6b030ea271e7"
Last-Modified: Wed, 29 Aug 2018 20:22:11 GMT
Link: <http://localhost:8080/static/constraints/ContainerConstraints.rdf>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Link: <http://localhost:8080/rest/path/to/resource>; rel="timegate"
Link: <http://localhost:8080/rest/path/to/resource>; rel="original"
Link: <http://localhost:8080/rest/path/to/resource/fcr:versions>; rel="timemap"
Memento-Datetime: Wed, 29 Aug 2018 21:21:34 GMT
Link: <http://mementoweb.org/ns#Memento>; rel="type"
Location: http://localhost:8080/rest/path/to/resource/fcr:versions/20180829212134
Content-Type: text/plain
Content-Length: 68
Server: Jetty(9.3.1.v20150714)

http://localhost:8080/rest/versioning/v9/fcr:versions/20180829212134

 

Status:

201 Created: if a new version is created successfully

404 Not Found: if the version container resource does not exist



Example 2 (Create a new versioned resource at the supplied time marker.  Its state is supplied as the request body.):

# Create version by supplying body and Memento-Datetime
curl -X GET http://localhost:8080/rest/path/to/resource > resource.ttl
curl -X POST -H "Memento-Datetime: Wed, 30 May 2018 23:02:44 GMT" -H "Content-Type: text/turtle" --data-binary "@resource.ttl"  http://localhost:8080/rest/path/to/resource/fcr:versions

Response:

HTTP/1.1 201 Created
Date: Wed, 29 Aug 2018 21:38:01 GMT
Set-Cookie: JSESSIONID=7bs7ddtba9l110261g9qyyotq;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Tue, 28-Aug-2018 21:38:01 GMT
ETag: W/"a6b6c76b16935d00bcd1b5f259cfd2ecb225e3bd"
Last-Modified: Wed, 29 Aug 2018 20:22:11 GMT
Link: <http://localhost:8080/static/constraints/ContainerConstraints.rdf>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Link: <http://localhost:8080/rest/path/to/resource>; rel="timegate"
Link: <http://localhost:8080/rest/path/to/resource>; rel="original"
Link: <http://localhost:8080/rest/path/to/resource/fcr:versions>; rel="timemap"
Memento-Datetime: Wed, 30 May 2018 23:02:44 GMT
Link: <http://mementoweb.org/ns#Memento>; rel="type"
Location: http://localhost:8080/rest/path/to/resource/fcr:versions/20180530230244
Content-Type: text/plain
Content-Length: 68
Server: Jetty(9.3.1.v20150714)

http://localhost:8080/rest/versioning/v9/fcr:versions/20180530230244

Status:

201 Created: if a new version is created successfully

400 Bad Request: Request body was empty or invalid.

404 Not Found: if the version container resource does not exist

409 Conflict: if a version with the same timestamp already exists for this resource.

415 Unsupported media type: If a Memento-Datetime is supplied without an accompanying Content-Type header to indicate the mime type.



DELETE Remove the versions container and all versioned resources


NB: In addition to deleting all versioned resources, the parent - or versionable resource - will no longer be versionable, meaning the parent resource cannot be versioned until made versionable again.


Example:

curl -X DELETE http://localhost:8080/rest/path/to/resource/fcr:versions


Response:

HTTP/1.1 204 No Content
Date: Wed, 29 Aug 2018 21:41:54 GMT
Set-Cookie: JSESSIONID=1hfa3law3t4kp3z3wjps3qw84;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Tue, 28-Aug-2018 21:41:54 GMT
Server: Jetty(9.3.1.v20150714)

Status:

204 No Content: if the version is reverted successfully

404 Not Found: if the version does not exist



Working with a versioned resource (a LDPRm)


Request URI: /path/to/resource/fcr:versions/<timestamp>

Methods: GET, DELETE

 

GET Get a specific versioned resource

Request Headers:

ACCEPT  application/ld+json, application/link-format, application/n-triples, application/rdf+xml, application/x-turtle, application/xhtml+xml, application/xml, text/html, text/n3, text/plain, text/rdf+n3, text/turtle

Example:

curl -H "Accept: text/turtle" http://localhost:8080/rest/path/to/resource/fcr:versions/20180829154750

Response:

HTTP/1.1 200 OK

Date: Thu, 30 Aug 2018 14:31:30 GMT
Set-Cookie: JSESSIONID=yb9ppso27n221q1xdvu4cqzi5;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Wed, 29-Aug-2018 14:31:30 GMT
ETag: W/"e766f5e674845e72f7d589e346b6a96a7735336e"
Last-Modified: Wed, 29 Aug 2018 15:47:31 GMT
Link: <http://www.w3.org/ns/ldp#Resource>;rel="type"
Link: <http://www.w3.org/ns/ldp#Container>;rel="type"
Link: <http://www.w3.org/ns/ldp#BasicContainer>;rel="type"
Link: <http://localhost:8080/static/constraints/ContainerConstraints.rdf>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Link: <http://localhost:8080/rest/path/to/resource>; rel="timegate"
Link: <http://localhost:8080/rest/path/to/resource>; rel="original"
Link: <http://localhost:8080/rest/path/to/resource/fcr:versions>; rel="timemap"
Allow: GET,HEAD,OPTIONS,DELETE
Memento-Datetime: Wed, 29 Aug 2018 15:47:50 GMT
Link: <http://mementoweb.org/ns#Memento>; rel="type"
Preference-Applied: return=representation
Vary: Prefer
Vary: Accept
Vary: Range
Vary: Accept-Encoding
Vary: Accept-Language
Content-Type: text/turtle;charset=utf-8
Content-Length: 1754
Server: Jetty(9.3.1.v20150714)

@prefix premis:  <http://www.loc.gov/premis/rdf/v1#> .
@prefix test:  <info:fedora/test/> .
@prefix memento:  <http://mementoweb.org/ns#> .
@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .
@prefix webac:  <http://fedora.info/definitions/v4/webac#> .
@prefix acl:  <http://www.w3.org/ns/auth/acl#> .
@prefix ns001:  <http://localhost:8080/rest/ktest/> .
@prefix xsi:  <http://www.w3.org/2001/XMLSchema-instance> .
@prefix xmlns:  <http://www.w3.org/2000/xmlns/> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix fedora:  <http://fedora.info/definitions/v4/repository#> .
@prefix xml:  <http://www.w3.org/XML/1998/namespace> .
@prefix ebucore:  <http://www.ebu.ch/metadata/ontologies/ebucore/ebucore#> .
@prefix ldp:  <http://www.w3.org/ns/ldp#> .
@prefix xs:  <http://www.w3.org/2001/XMLSchema> .
@prefix fedoraconfig:  <http://fedora.info/definitions/v4/config#> .
@prefix foaf:  <http://xmlns.com/foaf/0.1/> .
@prefix dc:  <http://purl.org/dc/elements/1.1/> .

<http://localhost:8080/rest/path/to/resource>
        rdf:type               ldp:RDFSource ;
        rdf:type               ldp:Container ;
        rdf:type               fedora:Resource ;
        rdf:type               ldp:BasicContainer ;
        rdf:type               fedora:Container ;
        fedora:created         "2018-08-29T15:47:31.041Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
        fedora:writable        true ;
        fedora:lastModified    "2018-08-29T15:47:31.041Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
        fedora:lastModifiedBy  "fedoraAdmin" ;
        fedora:createdBy       "fedoraAdmin" ;
        rdf:type               ldp:RDFSource ;
        rdf:type               ldp:Container ;
        fedora:writable        true .

Status:

200 OK

404 Not Found: Versions container resource does not exist.



DELETE Remove a previous version of an object

Example:

curl -i -X DELETE http://localhost:8080/rest/path/to/resource/fcr:versions/20180829154750


Response:

HTTP/1.1 204 No Content
Date: Thu, 30 Aug 2018 14:35:21 GMT
Set-Cookie: JSESSIONID=1w3ta3umg5nai1q4mtfp5qn48p;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Wed, 29-Aug-2018 14:35:21 GMT
Server: Jetty(9.3.1.v20150714)

Status:

204 No Content: if the version was deleted successfully

404 Not Found: if the version does not exist

Duplicate Versions

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)

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.

When restoring an old version, two operations occur:

  1. Immediately before restoring the old version, a version snapshot is made to reflect the current state of the object.  This version will not have a label starting with "auto-snapshot-before-".
  2. The current state of the resource will be updated to match the version being restored – but a new version will not be created.  You can create a version explicitly if you want to create a version that records the revert.

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. You may not, however, delete the most recent version snapshot

 

  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.