Summary

The VersionHistory resource represents the collection of the versions of a document.

Individual versions adhere to the documentVersion schema.

Status

Operation
Retrieving a document version history

Operations

Retrieve document version history

The VersionHistory for a document is returned. If the authenticated user can view the version history, the document resource will advertise a link with @rel value of version-history. To retrieve the document version history, GET the version-history URI.

The version may also include links to view the differences between a version and it's previous version (@rel difference-previous-version), and the differences between a version and the latest version (@rel difference-latest-version). This will only be returned if it possible to calculate and display the changes, which is currently limited to Word documents.

Also included is a template that can be used to generate an ad-hoc difference between any two versions. For futher information, please see see Document Version Difference.

Example

Request

GET /documents/123/versions HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    {"rel": "self", "href": "..."},
    {"rel": "parent", "href": "..."},
    {"rel": "download-all", "href": "..."}
  ],
  "versions": [
    {
      "links": [
        {"rel": "self", "href": "..."},
        {"rel": "content", "href": "...", "title": "..."},
        {"rel": "difference-previous-version", "href": "..."}
      ],
      "title": "a new title",
      "description": "a new description!!!!",
      "actors": [
        {
          "name": "Barry Potter",
          "email": "[email protected]",
          "rel": "updated-by",
          "links": [
            {"rel": "self", "href": "..."},
            {"rel": "avatar", "href": "..."},
            {"rel": "alternate", "href": "...", "type": "text/html"}
          ]
        }
      ],
      "versionNumber": 3,
      "size": 445645648,
      "created": "Wed, 23 May 2018 10:51:00 GMT",
      "updated": "Wed, 23 May 2018 10:51:00 GMT",
      "contentType": "application/msword"
    },
    {
      "links": [
        {"rel": "self", "href": "..."},
        {"rel": "content", "href": "...", "title": "..."},
        {"rel": "difference-previous-version", "href": "..."}
        {"rel": "difference-latest-version", "href": "..."}
      ],
      "title": "a different title",
      "description": "a different description!!!!",
      "actors": [
        {
          "name": "Barry Potter",
          "email": "[email protected]",
          "rel": "updated-by",
          "links": [
            {"rel": "self", "href": "..."},
            {"rel": "avatar", "href": "..."},
            {"rel": "alternate", "href": "...", "type": "text/html"}
          ]
        }
      ],
      "versionNumber": 2,
      "size": 445645648,
      "created": "Wed, 23 May 2018 10:49:00 GMT",
      "updated": "Wed, 23 May 2018 10:50:00 GMT",
      "contentType": "application/msword"
    },
     {
      "links": [
        {"rel": "self", "href": "..."},
        {"rel": "content", "href": "...", "title": "..."},
        {"rel": "difference-latest-version", "href": "...", "title": "..."}
      ],
      "title": "a title",
      "description": "a description!!!!",
      "actors": [
        {
          "name": "Barry Potter",
          "email": "[email protected]",
          "rel": "updated-by",
          "links": [
            {"rel": "self", "href": "..."},
            {"rel": "avatar", "href": "..."},
            {"rel": "alternate", "href": "...", "type": "text/html"}
          ]
        }
      ],
      "versionNumber": 1,
      "size": 445645648,
      "created": "Wed, 23 May 2018 10:41:00 GMT",
      "updated": "Wed, 23 May 2018 10:42:00 GMT",
      "contentType": "application/msword"
    }
  ],
  templates: [
    {
      "rel": "difference"
      "href": "/files/documents/{documentId}/versions/{sourceDocumentVersionId}/difference/{comparedToDocumentVersionId}",
      "vars": {
        "documentId": "https://api.huddle.{TLD}/param/document-id",
        "sourceDocumentVersionId": "https://api.huddle.{TLD}/param/document-version-id",
        "comparedToDocumentVersionId": "https://api.huddle.{TLD}/param/document-version-id"
      },
      "hints": {
        "allow": [ "GET", "POST" ]
      }
    }
  ]
}

---

Syntax

Example

{
  "links": [
    {"rel": "self", "href": "..."},
    {"rel": "parent", "href": "..."},
    {"rel": "download-all", "href": "..."}
  ],
  "versions": [
    {
      "links": [
        {"rel": "self", "href": "..."},
        {"rel": "content", "href": "...", "title": "..."},
        {"rel": "difference-previous-version", "href": "..."}
      ],
      "title": "a new title",
      "description": "a new description!!!!",
      "actors": [
        {
          "name": "Barry Potter",
          "email": "[email protected]",
          "rel": "updated-by",
          "links": [
            {"rel": "self", "href": "..."},
            {"rel": "avatar", "href": "..."},
            {"rel": "alternate", "href": "...", "type": "text/html"}
          ]
        }
      ],
      "versionNumber": 3,
      "size": 445645648,
      "created": "Wed, 23 May 2018 10:51:00 GMT",
      "updated": "Wed, 23 May 2018 10:51:00 GMT",
      "contentType": "application/msword"
    },
    {
      "links": [
        {"rel": "self", "href": "..."},
        {"rel": "content", "href": "...", "title": "..."},
        {"rel": "difference-previous-version", "href": "..."}
        {"rel": "difference-latest-version", "href": "..."}
      ],
      "title": "a different title",
      "description": "a different description!!!!",
      "actors": [
        {
          "name": "Barry Potter",
          "email": "[email protected]",
          "rel": "updated-by",
          "links": [
            {"rel": "self", "href": "..."},
            {"rel": "avatar", "href": "..."},
            {"rel": "alternate", "href": "...", "type": "text/html"}
          ]
        }
      ],
      "versionNumber": 2,
      "size": 445645648,
      "created": "Wed, 23 May 2018 10:49:00 GMT",
      "updated": "Wed, 23 May 2018 10:50:00 GMT",
      "contentType": "application/msword"
    },
     {
      "links": [
        {"rel": "self", "href": "..."},
        {"rel": "content", "href": "...", "title": "..."},
        {"rel": "difference-latest-version", "href": "...", "title": "..."}
      ],
      "title": "a title",
      "description": "a description!!!!",
      "actors": [
        {
          "name": "Barry Potter",
          "email": "[email protected]",
          "rel": "updated-by",
          "links": [
            {"rel": "self", "href": "..."},
            {"rel": "avatar", "href": "..."},
            {"rel": "alternate", "href": "...", "type": "text/html"}
          ]
        }
      ],
      "versionNumber": 1,
      "size": 445645648,
      "created": "Wed, 23 May 2018 10:41:00 GMT",
      "updated": "Wed, 23 May 2018 10:42:00 GMT",
      "contentType": "application/msword"
    },
  ]
}

Link relations

Name	Description	Methods
self	The current URI of this versionHistory.	GET
parent	The URI of the document.	GET
download-all	Download the content of all versions into a single zip file.	GET
latest-version	The URI of the latest version of the document.	GET
difference-previous-version	Generate and view the differences between this version and the previous version. For details on differences between document versions, see Document Version Difference.	GET, POST
difference-latest-version	Generate and view the differences between this version and the latest version. For details on differences between document versions, see Document Version Difference.	GET, POST

Schema

start = versionHistory

versionHistory = element h:versionHistory {
  link+,
  documentVersion+
}