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:

GET /news/@history HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk


HTTP/1.1 200 OK
Content-Type: application/json


[
  {
    "@id": "http://localhost:8000/news/@history/1",
    "action": "Edited",
    "actor": {
      "@id": "http://localhost:8000/@users/admin",
      "fullname": "Admin",
      "id": "admin",
      "username": "admin"
    },
    "comments": "Changed title",
    "may_revert": true,
    "time": "2022-04-04T20:22:00.000Z",
    "transition_title": "Edited",
    "type": "versioning",
    "version": 1
  },
  {
    "time": "2022-04-03T20:22:00.000Z",
    "actor": {
      "@id": "http://localhost:8000/@users/admin",
      "fullname": "Admin",
      "id": "admin",
      "username": "admin"
    },
    "action": "publish",
    "state_title": "Published",
    "review_state": "published",
    "transition_title": "Publish",
    "comments": "",
    "type": "workflow"
  },
  {
    "@id": "http://localhost:8000/news/@history/0",
    "action": "Edited",
    "actor": {
      "@id": "http://localhost:8000/@users/admin",
      "fullname": "Admin",
      "id": "admin",
      "username": "admin"
    },
    "comments": "Initial version",
    "may_revert": true,
    "time": "2022-04-02T20:22:00.000Z",
    "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.
  • type: ‘workflow’ for workflow changes, or ‘versioning’ for editing
  • 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.

GET /news/@history/0 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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.

PATCH /news/my-news-item/@history HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "version": 0
}


HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "My News Item has been reverted to revision 0."
}