DocumentVersion - Huddle/huddle-apis GitHub Wiki

DocumentVersion

The DocumentVersion resource represents one distinct version of a Document.

Operations

Method Path Purpose Details
GET /files/documents/123/version/456 Get a document version Jump
POST /files/documents/123/version Create a document version Jump
POST /files/documents/123/promote/latest Promote auto-save to published version Jump
DELETE /files/documents/123/version/456 Delete a document version Jump

Get a document version

To retrieve a specific version of a document, issue a GET request to the version's self link (advertised in the VersionHistory resource).

Response codes

Code Description
200 OK Version returned successfully.
403 Forbidden Insufficient permission to read this version.
404 Not Found Document or version not found.

Example

Request

GET /files/documents/123/version/456 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

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

<documentVersion title="My Document" description="A description" versionNote="Fixed typos" extension="docx">
  <link rel="self" href=".../files/documents/123/version/456" />
  <link rel="delete" href=".../files/documents/123/version/456" />
  <link rel="content" href=".../files/documents/versions/456/content" title="my-document.docx" />
  <link rel="parent" href=".../files/documents/123" />
  <link rel="version-history" href=".../files/documents/123/versions" />

  <actor name="Barry Potter" rel="updated-by">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
  </actor>

  <size>445645648</size>
  <version>2</version>
  <contentType>application/msword</contentType>
  <created>2011-02-15T09:43:17Z</created>
  <updated>2011-02-19T14:28:04Z</updated>
</documentVersion>

Create a document version

To create a new version of a document, issue a POST request to the document's version URI. The request body should contain the new version's metadata. Binary content is uploaded separately after the version is created (see the upload link in the response).

Request body

<documentVersion 
  title="My Document" 
  description="Updated description" 
  versionNote="Added new section" 
  extension="docx" 
/>

Response codes

Code Description
201 Created Version created. Response body contains the updated Document resource and a Location header pointing to it.
400 Bad Request Missing or invalid upload headers.
409 Conflict A lock conflict prevents creating a new version. Response body contains lock details.

Example

Request

POST /files/documents/123/version HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty
Content-Type: application/xml

<documentVersion 
  title="My Document" 
  description="Updated description" 
  versionNote="Added new section" 
  extension="docx" 
/>

Response

HTTP/1.1 201 Created
Location: .../files/documents/123
Content-Type: application/xml

... Document resource ...

Promote auto-save to published version

Some clients create auto-save versions of documents. To promote the latest auto-save to a published version, issue a POST request to the document's promote/latest URI.

Response codes

Code Description
201 Created Auto-save promoted successfully. Response body contains the updated Document resource.
204 No Content No auto-save content is available to promote.
409 Conflict An upload is currently in progress; try again later.

Example

Request

POST /files/documents/123/promote/latest HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response (success)

HTTP/1.1 201 Created
Location: .../files/documents/123
Content-Type: application/xml

... Document resource ...

Response (no auto-save to promote)

HTTP/1.1 204 No Content

Delete a document version

If the authenticated user can delete a document version, the DocumentVersion contained in the VersionHistory resource will advertise a link with a rel value of delete. To delete the version, issue a DELETE request to that URI.

Response codes

Code Description
200 OK Version deleted. Response includes a Link header to the version history and parent document.
403 Forbidden Insufficient permission to delete this version.
404 Not Found Document or version not found.

Example

Request

DELETE /files/documents/123/version/456 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Link: <.../files/documents/123/versions>;rel="version-history", <.../files/documents/123>;rel="parent"

Syntax

Example

<documentVersion title="My Document" description="A description" versionNote="Fixed typos" extension="docx">
  <link rel="self" href="..." />
  <link rel="delete" href="..." />
  <link rel="content" href="..." title="my-document.docx" />

  <actor name="Barry Potter" rel="updated-by">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
  </actor>

  <size>445645648</size>
  <version>2</version>
  <contentType>application/msword</contentType>
  <created>2011-02-15T09:43:17Z</created>
  <updated>2011-02-19T14:28:04Z</updated>
</documentVersion>

Link relations

Name Description Methods
self The current URI of this documentVersion. GET
delete Delete this version (only advertised if the user has permission). DELETE
content The binary content for this version. GET
parent The parent document. GET
version-history The version history collection. GET
difference-previous-version Compare this version to the previous version. GET, POST
difference-latest-version Compare this version to the latest version. GET, POST
download-all Download all versions as a ZIP (only advertised if the user has GetContent permission). GET

Schema

start = documentVersion

documentVersion = element h:documentVersion {
  attribute title {xsd:string},
  attribute description {xsd:string}?,
  attribute versionNote {xsd:string}?,
  attribute extension {xsd:string}?,
  link+,
  actor,
  element h:size {xsd:unsignedLong},
  element h:version {xsd:unsignedInt},
  element h:contentType {xsd:string},
  element h:created {xsd:dateTime},
  element h:updated {xsd:dateTime}
}
⚠️ **GitHub.com Fallback** ⚠️