Difference - Huddle/huddle-apis GitHub Wiki

Summary

As a document changes, it is useful for users to understand the changes between versions. The Difference API allows you to generate a visual representation of the difference and a summary of the changes.

Status

Operation
Difference between a version and its previous version within a document
Difference between a version and another version within a document

Determining if "difference" is supported for a document

If the difference feature is available for a document, the Document GET will return a "difference-previous-version" link and a "difference" link.. The Document Difference feature must be enabled on your account and on the workspace the document resides in.

Difference between a version and its previous version within a document

You can create a difference between a version and its previous version within a document. The Difference API can return a PDF representation of both versions, with differences highlights AND can return a statistical summary of those difference.

Example

Request

GET /files/documents/123 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": "difference-previous-version",
       "href": "/files/documents/123/versions/1000/difference/previous"
   },
   ...
 ],
 ...
 [other document elements]
}

Creating a difference between a version and its previous versions within a document

If you issue a GET at the "difference-previous-version" link, and receive a 404, then the difference has not yet been created. In order to create it, issue a POST at the link.

Request

POST /files/documents/123/versions/1000/difference/previous HTTP/1.1
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 202 Accepted

The difference will now be generating. In order to track progress poll the resource until you receive a 200. The best practice is to poll this resource for 30 seconds and then assume that the difference has not been created and give up.

Retrieving a difference between a version and its previous versions within a document

If the difference exists, you will be returned a response detailing the difference assets. Note that self link has been translated from

/files/documents/123/versions/1000/difference/previous to the more terse alias uri /files/documents/123/versions/900/difference/1000

Where version 900 is the previous version of 1000.

Example

Request

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

Response

HTTP/1.1 200 Accepted
Content-Type: application/vnd.huddle.data+jon

{
   "links": [ {
       "rel": "self",
       "href": "/files/documents/123/versions/900/difference/1000"
   }, {
       "rel": "contents",
       "href": "/files/documents/123/versions/7303/difference/1000/content/difference.pdf"
   }, {
       "rel": "summary",
       "href": "/files/documents/123/versions/7303/difference/1000/content/difference.json"
   } ]
}

The contents link gives a visual representation of the difference. The summary link gives statistics about the difference.

Difference between a version and another version within a document within a document

You can create a difference between a version and another version within a document. The Difference API can return a PDF representation of both versions, with differences highlights AND can return a statistical summary of those difference.

The difference link is instructing you to refer to the json-home endpoint to look up how to construct a difference link. See API "Home Document"

Example

Request

GET /files/documents/123 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+xml

{
 ...
 "links": [ {
       "rel": "http://api.huddle.{TLD}/rel/files/difference",
       "href": "http://api.huddle.{TLD}",
       "type": "application/json-home"
   },
   ...
 ],
 ...
 [other document elements]
}

Request

GET http://api.huddle.{TLD}
Content-Type: application/json-home

Response

HTTP/1.1 200 OK
Content-Type: application/json-home
{
  "resources": {
    ...
    "http://api.huddle.net/rel/files/difference": {
        "href-template": "/files/documents/{document-id}/versions/{source-document-version-id}/difference/{compared-to-document-version-id}",
       "href-vars": {
         "document-id": "http://api.huddle.{TLD}/param/document-id",
          "source-document-version-id": "http://api.huddle.{TLD}/param/document-version-id",
          "compared-to-document-version-id": "http://api.huddle.{TLD}/param/document-version-id"
        },
 		"hints": {
      		"allow": ["GET", "POST"]
      	}
   }
  ...
  }
}

Now you can look up "http://api.huddle.{TLD}/rel/files/difference" from the response body to find out how to construct the link.

e.g. /files/documents/123/versions/900/difference/1000

Creating a difference between a version and another version within a document within a document

If you issue a GET at the client constructed "difference" link, and receive a 404, then the difference has not yet been created. In order to create it, issue a POST at the link.

Request

POST /files/documents/123/versions/900/difference/1000 HTTP/1.1
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 202 Accepted

The difference will now be generating. In order to track progress poll the difference resource until you receive a 200. The best practice is to poll this resource for 30 seconds and then assume that the difference has not been created and give up.

Retrieving a difference between a version and another version within a document within a document

If the difference exists, you will be returned a response detailing the difference assets.

Example

Request

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

Response

HTTP/1.1 200 Accepted
Content-Type: application/vnd.huddle.data+jon

{
   "links": [ {
       "rel": "self",
       "href": "/files/documents/123/versions/900/difference/1000"
   }, {
       "rel": "contents",
       "href": "/files/documents/123/versions/7303/difference/1000/content/difference.pdf"
   }, {
       "rel": "summary",
       "href": "/files/documents/123/versions/7303/difference/1000/content/difference.json"
   } ]
}

The contents link gives a visual representation of the difference. The summary link gives statistics about the difference.