Overview
Within Fedora 4, snapshots of the current state of a resource may be saved into the version history. The RDF for historic version shapshots may be browsed and old non-RDF content may be downloaded. Furthermore, an object or subgraph 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. When saving these versions you must provide a label that both serves to easily differentiate a version from another and allow easy retrieval of that version.
Click to expand the full REST API Documentation...
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: 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
Response:
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: 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.
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 may do so using the REST API, 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 (and possibly the sub-graph) to the version viewed.
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
14 Comments
Andrew Woods
Michael Durbin, It will be helpful to include sample REST calls as well as CND configurations.
Greg Jansen
Michael Durbin, does a version include child nodes all the way down? IOW is a version a snapshot of the tree or of the one node?
Michael Durbin
This is a good question Greg that likely exposes some shortcomings with our current versioning implementation and node type configuration.
It depends on the children. If a child is not versionable or has an "on parent version" property of "copy", that node and the entire subgraph is copied. A little testing has shown me that if you auto-generate an ID the placeholder nodes are not versionable, causing this copy to go into effect. If a child is versionable (like any fedora:resource in the default configuration) the spec says a special child with a reference to the version history of the child is supposed to be added.
http://www.day.com/specs/jcr/2.0/3_Repository_Model.html#3.13.9%20Versionable%20State
Greg Jansen
It sounds as if versionable children would be more efficient, i.e. pointers instead of copies when the parent is versioned.. Being versionable without auto-versioning seems like a good thing.
Yinlin Chen
Can we see all the vision history in Web interface? I create several versions for a certain node and click fcr:versions link. It shows only two links, one root and a version. That version is not the latest created version.
Andrew Woods
Yes, all versions are in the web interface. If you do not see a specific version there, that means a specific version was not created (assuming there is not a bug). Can you describe the process by which you are "creating versions"?
Yinlin Chen
I can see all versions through command line:
curl -H "Accept: text/turtle" http://54.210.99.139:8080/fcrepo-webapp-4.0.0-beta-01/rest/test:3/fcr:versions
In Web GUI: I only see two: http://54.210.99.139:8080/fcrepo-webapp-4.0.0-beta-01/rest/test:3/fcr:versions
Create version command: curl -X POST http://54.210.99.139:8080/fcrepo-webapp-4.0.0-beta-01/rest/test:3/fcr:versions
Andrew Woods
Thanks, Yinlin Chen. I am seeing the same issue.
https://www.pivotaltracker.com/story/show/75910204
Justin Coyne
Is "version name" the same as "version label"? Both terms are used in this document and it's unclear what the difference is if any.
Andrew Woods
When I search for "name" in this document, I only come up with one result... which is not the same as a version label.
Are you seeing something else?
Justin Coyne
"When saving these versions you can optionally provide a label". This is not true after https://github.com/fcrepo4/fcrepo4/commit/5074ed63c30051cc1179eb688ce44ded95bafc54
Justin Coyne
Also the "Create a new version of an object" (without a name) example needs to be removed
Geetha
Hi,
I have a query in my usecase. Please help me to solve.
This is my scenario :
I have to do API versioning. I am using REST APIs with Restlet framework. I am confused how to implement the versioning in Java Source code.
If my API looks like this : http://localhost:8080/example.com/v2/hello
Then In my source code how to map the version with appropriate functionality?
For example :
If(version == 1) {//Do Version 1 Source Code}
else If(version == 2) {//Do Version 2 Source Code}
else If(version == 3) {//Do Version 3 Source Code} ………..
If I did like this, Then why we are going for Versioning. We can implement Manually Right? And also If I have to add some 100 versions, then the code looks uglier and it becomes lengthier.
I get confused how to map in Source Code. Please Clarify my doubt.
I have read that we can use annotations for handling API versioning. But I don't know what are the annotations available in restlet framework. Please let me know.
Regards,
Geetha.
Unknown User (escowles@ucsd.edu)
Geetha, this wiki page is documentation of versioning in the Fedora Repository, where versioning is used to store different states of repository content, not to separate different REST API versions.