History

The @history endpoint exposes history and versioning information on previous versions of the content. Each change or workflow change on a content object or file is listed. It also allows to revert to a previous version of the file.

Listing the History of a Content Object

Listing versions and history of a resource:

http

GET /plone/front-page/@history HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@history -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/front-page/@history Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@history', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "action": "Create", 
    "actor": {
      "@id": "http://localhost:55001/plone/@users/test_user_1_", 
      "fullname": "", 
      "id": "test_user_1_", 
      "username": "test-user"
    }, 
    "comments": "", 
    "review_state": "private", 
    "state_title": "Private", 
    "time": "2016-10-21T19:00:00", 
    "transition_title": "Create", 
    "type": "workflow"
  }, 
  {
    "@id": "http://localhost:55001/plone/front-page/@history/0", 
    "action": "Edited", 
    "actor": {
      "@id": "http://localhost:55001/plone/@users/test-user", 
      "fullname": "test-user", 
      "id": "test-user", 
      "username": null
    }, 
    "comments": null, 
    "may_revert": true, 
    "time": "2016-10-21T19:00:00", 
    "transition_title": "Edited", 
    "type": "versioning", 
    "version": 0
  }
]

This following fields are returned:

  • action: the workflow transition id, ‘Edited’ for versioning, or ‘Create’ for initial state.
  • actor: the user who performed the action. This contains a subobject with the details.
  • comments: a changenote
  • @id: link to the content endpoint of this specific version.
  • may_revert: true if the user has permission to revert.
  • time: when this action occured in ISO format.
  • transition_title: the workflow transition’s title, ‘Edited’ for versioning, or ‘Create’ for initial state.
  • type: ‘workflow’ for workflow changes, ‘versioning’ for editing, or null for content creation.
  • version: identifier for this specific version of the resource.

Get a Historical Version

Older versions of a resource can be retrieved by appending version to the @history endpoint url.

http

GET /plone/folder/my-document/@history/0 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/folder/my-document/@history/0 -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/folder/my-document/@history/0 Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/folder/my-document/@history/0', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Revert to a Historical Version

Reverting to an older versions of a resource can be done by sending a PATCH request to the @history endpoint and appending the version you want to revert to.

http

PATCH /plone/front-page/@history HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "version": 0
}

curl

curl -i -X PATCH http://nohost/plone/front-page/@history -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"version": 0}' --user admin:secret

httpie

echo '{
  "version": 0
}' | http PATCH http://nohost/plone/front-page/@history Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/front-page/@history', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'version': 0,
}, auth=('admin', 'secret'))
HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Welcome to Plone has been reverted to revision 0."
}