Table of Contents |
---|
WORK IN PROGRESS - Kevin Ford has this, it's just taking some time. |
---|
Versioning in Fedora is composed of three specific types of resources - a versionable resource, a versions container, and the actual versioned resources - 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.
Excerpt | |||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Working with a versionable resourceA 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.
| |||||||||||||||||||||||||||||||||||||||||
Excerpt | |||||||||||||||||||||||||||||||||||||||||
A Note on Versionable ResourcesThe following documented API calls are based on the assumption that the resource located at /path/to/some/resource was created as a versionable resource. You can make a resource verisonable by simply adding the following link header to your PUT or POST commands when creating or updating your resource.
Examples:
| |||||||||||||||||||||||||||||||||||||||||
Excerpt | |||||||||||||||||||||||||||||||||||||||||
Request URI:
Request URI: /path/to/some/resource/fcr:versions Methods: GET, PUT, POST, PATCH
Get a list of the available versions of an object Status |
Retrieve the versioned resource from a specific point in time.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: -datetime An RFC-1123 Date. (E.g. "Wed, 30 May 2018 23:02:44 GMT") Example:
Response:
Status:
Examples:
|
Excerpt | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Working with a versions container Request URI: /path/to/resource/fcr:versions Methods: GET, POST, DELETE
Status |
|
Code Block |
---|
curl -H "Accept: text/turtle" http://localhost:8080/rest/path/to/resource/fcr:versions |
Response:
Code Block |
---|
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/20180530210300> ; ldp:contains <http://localhost:8080/rest/path/to/resource/fcr:versions/20180530210354> . |
Status:
Status | ||||||
---|---|---|---|---|---|---|
|
Response: The requested resource is not available.
Status | ||
---|---|---|
|
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:
Code Block |
---|
curl httpfcr: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/<timestamp> |
Response:
Code Block |
---|
Status: HTTP/1.1 200 OK Headers: Date: Wed, 30 May 2018 21:11:01 GMT ETag: W/"706475b002bad44f8e5d874b8e7c3b1d35ff9a1c" Last-Modified: Wed, 30 May 2018 21:00:48 GMT Link: <http://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/ns/ldp#Resource>;rel="type" Link: 1999/02/22-rdf-syntax-ns#> . @prefix fedora: <http://www.w3.org/ns/ldp#Container>;rel="type" Link: fedora.info/definitions/v4/repository#> . @prefix ldp: <http://www.w3.org/ns/ldp#BasicContainer>;rel="type" Memento-Datetime: Wed, 30 May 2018 21:03:54 GMT Link: <http://mementoweb.org/ns#Memento>; rel="type" Link: ldp#> . <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 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: 1793 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#> . <httprest/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:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status colour Blue title POST
Create a new version resource (a memento of an object).
colour | Blue |
---|---|
title | POST |
Versions can by created in one of two ways. 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.):
Code Block |
---|
# Create version from current state of the object
curl -X POST http://localhost:8080/rest/path/to/resource/fcr:versions
|
Response:
Code Block |
---|
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:
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Example 2 (Create a new version resource at the supplied time marker. Its state is supplied as the request body.):
Code Block |
---|
# 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:
Code Block |
---|
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:
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
Status colour Red title DELETE
Remove a previous version of an object
colour | Red |
---|---|
title | DELETE |
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:
Code Block |
---|
curl -X DELETE http://localhost:8080/rest/path/to/resource/fcr:versions |
Response:
Code Block |
---|
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:
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Excerpt | |||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Working with a versioned resource Request URI: /path/to/resource/fcr:versions/<timestamp> Methods: GET, DELETE
Status |
|
Code Block |
---|
curl -H "Accept: text/turtle" http://localhost:8080/rest/path/to/resource/fcr:versions |
Response:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status colour Blue title POST
Create a new version resource (a memento of an object).
colour | Blue |
---|---|
title | POST |
Versions can by created in one of two ways. 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.):
Code Block |
---|
# Create version from current state of the object curl -X POST http://localhost:8080/rest/path/to/resource/fcr:versions |
Response:
Code Block |
---|
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/resource/fcr:versions/20180530210354> rdf:type ldp:RDFSource ; rdf:type ldp:Container ; rdf:type fedora:Resource ; rdf:type ldp:BasicContainer ; rdf:type fedora:Container ; fedora:created "2018-05-30T21:00:48.169Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; fedora:writable true ; fedora:lastModified "2018-05-30T21:00:48.169Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; fedora:lastModifiedBy "bypassAdmin" ; fedora:createdBy "bypassAdmin" ; rdf:type ldp:RDFSource ; rdf:type ldp:Container ; fedora:writable true . * Connection #0 to host localhost left intact |
Response: The requested resource is not available.
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:
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Example 2 (Create a new version resource at the supplied time marker. Its state is supplied as the request body.):
Code Block |
---|
Request Headers
MEMENTO-DATETIME (Optional) An RFC-1123 Date. (E.g. "Wed, 30 May 2018 23:02:44 GMT")
NB: Versions can by created in one of two ways. If the Memento-Datetime header is omitted, the current time will be used by default. You may supply a request body representing state of the resource to be versioned when the Memento-Datetime header is present. If no Memento-Datetime header is present, any specified body will be ignored. Instead, the current state of the resource will be used as the body for the memento.
Example:
Code Block |
---|
# Create version from current state of the object
curl -X POST http://localhost:8080/rest/path/to/resource/fcr:versions
# 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:
Code Block |
---|
Status: HTTP/1.1 201 Created Headers: Date: Wed, 30 May 2018 23:02:44 GMT 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/"7a7cb9a13ca1cbd1794ef36292f682e0fd7675b0a6b6c76b16935d00bcd1b5f259cfd2ecb225e3bd" Last-Modified: Wed, 3029 MayAug 2018 2120:0022:4811 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: 71 Body:68 Server: Jetty(9.3.1.v20150714) http://localhost:8080/rest/pathversioning/tov9/resource/fcr:versions/20180530230244 |
Status:
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
Response:
Memento with provided datetime already exists.
Request URI: /path/to/some/resource/fcr:versions/<timestamp>
Methods: DELETE
Status colour Red title DELETE
Remove a previous version of an object
colour | Red |
---|---|
title | DELETE |
Example:
Code Block |
---|
curl -X DELETE http://localhost:8080/rest/path/to/resource/fcr:versions/<timestamp> |
Response:
Code Block |
---|
Status: 204 No Content Headers: Date: Wed, 30 May 2018 23:58:28 GMT |
Status:
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Response: Cannot remove current version
Status | ||||||||
---|---|---|---|---|---|---|---|---|
|
Response: The requested resource is not available.
...