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 26 Next »

Overview

Within Fedora 4, snapshots of the current state of an object may be saved into the version history either through explicit user requests or during each update to that object.  The properties or content of a node saved in these version checkpoints may be accessed later to serve as a historical record of the object.  Future feature development may allow for easy export of the entire history or other useful actions.

Enabling Versioning

By default, versioning is disabled for all nodes.  When you make a request to create a version, the mix:versionable mixin is added to that node automatically.

This mixin can also be added manually using SPARQL Update:

Enable Versioning via the REST API
echo "insert data { <> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.jcp.org/jcr/mix/1.0versionable> . }" \
| curl -X PATCH --upload-file - http://localhost:8080/rest/path/to/object

Enabling versioning for all nodes is incompatible with read/write filesystem federation.  If you are not using filesystem federation (or only read-only), you can make all nodes versionable by default.

Creating versions

Explicit version creation

When you wish to save a snapshot of the current version of a node to the version history you can use the REST API.  When saving these versions you can optionally provide a label that both serves to easily differentiate a version from another and allows easy retrieval of that version.

 

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

Methods: GET, POST, PATCH

 

GET Get a list of the available versions of an object

Request Headers:

ACCEPT  application/ld+json, 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: 200 OK

Headers:
Content-Type: text/turtle

Body:
<http://localhost:8080/rest/path/to/resource> fedora:hasVersion <http://localhost:8080/rest/path/to/resource/fcr:versions/87a0a8c317f1e749515d33-cb73-4fd7-9d1d-c715eb6947e0> .
<http://localhost:8080/rest/path/to/resource/fcr:versions/87a0a8c317f1e749515d33-cb73-4fd7-9d1d-c715eb6947e0> fedora:hasVersionLabel "v0"^^<http://www.w3.org/2001/XMLSchema#string> ;
        fedora:created "2014-12-03T23:55:38.47Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

<http://localhost:8080/rest/path/to/resource> fedora:hasVersion <http://localhost:8080/rest/path/to/resource/fcr:versions/87a0a8c317f1e7dae533ec-b1b6-4da1-8bb9-f1964e253572> .
<http://localhost:8080/rest/path/to/resource/fcr:versions/87a0a8c317f1e7dae533ec-b1b6-4da1-8bb9-f1964e253572> fedora:hasVersionLabel "v1"^^<http://www.w3.org/2001/XMLSchema#string> ;
        fedora:created "2014-12-03T23:56:12.863Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

Status:

200 OK

404 Not Found: This resource is not versioned or this resource is not exist.

Response: The requested resource is not available.

 


GET Get a previous version of an object

Request Headers:

ACCEPT  application/ld+json, 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 http://localhost:8080/rest/resource/fcr:versions/<version-label>

Response:

Status: 200 OK

Response Headers:
ETag: "39f0d8a01a066771e56f70be892a39a7b505843c"
Last-Modified: Tue, 20 May 2014 19:29:10 GMT
Content-Type: text/turtle

Body:

<http://localhost:8080/rest/resource/fcr:versions/87a0a8c317f1e72c658170-624d-40f9-96cb-21ede3392155> <http://fedora.info/definitions/v4/repository#primaryType> "nt:frozenNode"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#frozenPrimaryType> "nt:folder"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#created> "2014-05-20T19:29:00.192Z"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#frozenMixinTypes> "fedora:resource"^^<http://www.w3.org/2001/XMLSchema#string> , "mix:versionable"^^<http://www.w3.org/2001/XMLSchema#string> , "fedora:object"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#lastModified> "2014-05-20T19:29:10.555Z"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#frozenUuid> "fed529c6-2121-4b1d-83fc-cc4274563612"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#lastModifiedBy> "bypassAdmin"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#uuid> "87a0a8c317f1e72c658170-624d-40f9-96cb-21ede3392155"^^<http://www.w3.org/2001/XMLSchema#string> ;
    <http://fedora.info/definitions/v4/repository#createdBy> "bypassAdmin"^^<http://www.w3.org/2001/XMLSchema#string> ;
    a <http://www.jcp.org/jcr/nt/1.0frozenNode> , <http://www.jcp.org/jcr/nt/1.0base> , <http://www.jcp.org/jcr/mix/1.0referenceable> .

Status:

200 OK

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

Response: The requested resource is not available.

 


POST Create a new version of an object

Request Headers

SLUG (Required) A suggested name for the new child resource, which the repository may ignore.

Example:

curl -X POST -H "Slug: newVersionName" http://localhost:8080/rest/path/to/resource/fcr:versions

Response:

Status: 204 No Content

 

Status:

204 No Content: if a new version is created successfully

404 Not Found: if the resource does not exist

409 Conflict: if the version label is already in use for another version of this rexource

Response: The requested resource is not available.



 PATCH Revert to a previous version of an object

Example:

curl -X PATCH http://localhost:8080/rest/path/to/resource/fcr:versions/existingVersionName
For previous versions for which explicit names were not provided, you may use the UUID property which you can find by parsing the response from the listing of available versions.

 

Response:

Status: 204 No Content

Status:

204 No Content: if the version is reverted successfully

404 Not Found: if the version does not exist

Response: The requested resource is not available.

 

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

Methods: DELETE

DELETE Remove a previous version of an object

Example:

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


Response:

Status: 204 No Content

Trying to delete the current version of a resource will result in an error.  To revert to an old version of a resource, first revert to the old version using the PATCH method, and then delete the newer version.

Status:

204 No Content: if the version is reverted successfully

400 Bad Request: if trying to delete the most recent version

Response: Cannot remove current version

404 Not Found: if the version does not exist

Response: The requested resource is not available.

Duplicate Version Labels

If a second version is created with the same label as a previous version, that label is quietly reassigned to the most recent version tagged with that label.

Version creation is a relatively costly operation.  With the ability to create versions whenever you wish, you can develop workflows that maximize the utility of the version history.

Possible strategies include:

  • For batch operations, only create version checkpoints once nodes have been ingested, verified and tested.
  • For high value but small data such as descriptive metadata entered by subject experts, set a versioning policy to store every modification to capture the entirety of the curatorial endeavor.
  • Create snapshot versions that correspond to released versions of content (ie, version X of a shared dataset, controlled vocabulary or collection)

Viewing old Versions

From the HTML view (or by issuing HTTP GET methods in an HTTP client program) you can get the version history of a node by appending "/fcr:versions" to it's base URL.  The root version will always be listed and represents the object at inception.  Following the root version will be any other versions created.  When labels have been specified, those labels will be displayed, otherwise the version will be identified by the modification date. 

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 and certain properties have been stored in different property names (mixin types, uuid) but you can export that snapshot or view any content.

Reverting to a previous version

If you wish to restore an object to a previous version you may do so using the REST API, or even the HTML view.  In the HTML view of a historic version, a button exists on the right hand side saying "Revert to this Version" that when clicked restores the object (and possibly the subgraph) to the version viewed.

Immediately before restoring an old version, a version snapshot is made to reflect the current state of the object.

  • No labels

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