Skip to content

Document

Jump to bottom
Nur Aina Shazwani Zakaria edited this page Mar 7, 2025 · 31 revisions

Summary

Documents represent files stored within Huddle, including spreadsheets, PDFs, images, and more. Each document has associated metadata, such as comments, activity history, version history, and other relevant details.

Operations

Operation
Retrieving a Document
Downloading Document Content
Publishing
Approvals
Lock
Updating Document Title and Descriptions
Moving a Document
Creating a New Version of a Document
Difference between document versions
Version Promotion
Deleting a Document
Copying a Document
Retreiving a Document Thumbnail
Tags
Pins
Comments
Changes
Sharing a Document
Previews
Last viewed version of document

Retrieving a Document

When retrieving a folder, the folder response will contain a list of documents existed within the folder. Each document will advertise a @rel value of self link, which can be used to GET the full document's details. This endpoint also supports HEAD request.

If a document's processing status is completed, the document resource will advertise a @rel value of content, latest-content, and print-preview link.

An If-Modified-Since header can be specified in the Request header to indicate that only if there are changes to the document resource since the specified time. Additionally, the Last-Modified is included in the response to indicate the last time the document resource was generated.

Example

Request

Sent a GET request to the document's self URI to get the document resource.

GET /files/documents/123 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Last-Modified: Thu, 04 Dec 1986 12:45:26 GMT
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document" mimetype="application/..." description="My Document Descriptions" extension="docx">
        <lock>...lock element is returned if a document is locked...</lock>
        <created>2025-01-15T02:44:30.213Z</created>
        <updated>2025-01-24T08:05:21.957Z</updated>
        <version>2</version>
        <actor name="Ian Cooper" email="ian.cooper@example.com" rel="owner">
            <link>...other actor links elements...</link>
        </actor>
        <size>1234</size>
        <processingStatus>Complete</processingStatus>
        <views>5</views>
        <workspace title="My Workspace">
            <link rel="self" href="... />
            <link rel="alternate" href="..."" />
            <link rel="pinneditems" href="..." />
            <downloadEnabled>true</downloadEnabled>
            <printEnabled>true</printEnabled>
        </workspace>
        <publications>
            ...if document is not published...
            <scope>none</scope>
            ...if document is published...
            <scope>public</scope>
            <publishedDate>2014-06-15T09:43:17Z</publishedDate>
            <link rel="bookmark" href="..." />
            <documentVersion title="My document is amazing">
               <link rel="self" href="..." />
               <version>2</version>
               <contentType>application/pdf</contentType>
            </documentVersion>
        </publications>
        ...approval element is returned if document has approval...
        <approval>
            <status>Complete</status>
            <actor name="Ian Cooper" email="ian.cooper@example.com" rel="requester">
                <link>...other actor links elements...</link>
            </actor>
        </approval>
        ...assignment element is returned if document has assigned approval...
        <assignment>
            <actor name="Ian Cooper" email="ian.cooper@example.com" rel="assignee">
                <link>...other actor links elements...</link>
            </actor>
            <status>Rejected</status>
            <created>2025-01-24T04:09:07.597Z</created>
            <link rel="self" href="..." />
            ...if status is open...
            <link rel="edit" href="..." />
            ...if status is complete... 
            <completed>2025-01-24T04:09:07.597Z</completed>
            ...for more info, go to [Approvals](#approvals)
        </assignment>
        <link rel="content" href="/files/documents/1234/content" type="application/..." title="My Document.docx" />
        <link rel="latest-content" href="/files/documents/1234/versions/latest/content" type="application/..." title="My Document.docx" />
        <link rel="print-preview" href="..." />
        <link rel="integrations" href="..." />
        <link rel="parent" href="..." title="My Folder" />
        <link rel="paged-parent-folder" href="..." title="My Workspace" />
        <link rel="parent-folder" href="..." title="My Folder" />
        <link rel="bulk-delete" href="..." />
        <link rel="edit" href="..." />
        <link rel="create-version" href="..." />
        <link rel="promote-latest" href="..." />
        <link rel="lock" href="..." />
        <link rel="publish" href="..." />
        ...if document is published...
        <link rel="unpublish" href="..." />
        <link rel="delete" href="..." />
        <link rel="move" href="..." />
        <link rel="copy" href="..." />
        <link rel="self" href="..." />
        <link rel="last-viewed" href="..." />
        <link rel="version-history" href="..." />
        <link rel="comments" href="..." count="11" />
        <link rel="comments-paged" href="..." count="11" />
        <link rel="approvals" href="..." />
        <link rel="viewed" href="..." />
        <link rel="tasksUri" href="..." />
        <link rel="permissions" href="..." />
        <link rel="share" href="..." />
        <link rel="audittrail" href="..." />
        <link rel="current-lock" href="..." />
        <link rel="previews" href="..." />
        <link rel="alternate" href="..." />
        <link rel="alternate" href="..." type="text/html" />
        <link rel="shortlink" href="..." type="text/html" />
        <link rel="recipients" href="..." />
        <link rel="make-offline" href="..." />
        <link rel="tags" href="..." />
        <link rel="pin" href="..." />
        <link rel="difference-previous-version" href="..." />
       ...if document mimeType support thumbnails...
        <thumbnails>
            <thumbnail type="medium">
                <link rel="content" href='...' />
            </thumbnail>
        </thumbnails>
        ...if document has tags...
        <tags>
            <tag value="documentation">
                <link rel="self" href="...files/documents/123/tags/documentation" />
            </tag>
        </tags>
        ...pin element is returned if document is pinned...
        <pin>
            <link rel="self" href="..."/>...
            <link rel="delete" href="..."/>
            <pinnedDate>2018-05-10T09:02:17Z</pinnedDate>
            <actor name="Ian Cooper" email="ian.cooper@example.com" rel="pinned-by">
                <link>...other actor links elements...</link>
            </actor>
            ...for more info, go to [Pinning a document](https://github.com/Huddle/huddle-apis/wiki/Pins#pinning-a-document)
        </pin>
</document>

Downloading Document Content

If the authenticated user has permissions to download and print a document, the document resource will advertise a link with a @rel value of content. For more information on document content operations, please visit Document Content

Publishing

If the authenticated user has permissions to publish a document, the document resource will advertise a link with a @rel value of publish and set the publications elements to none. For more information on publishing a document, please visit Publish Documents.

If a document is published, the document resource will advertise a link with a @rel value of unpublish and the publications elements containing the publications details. For more information on the published document, please visit Published Document.

Approvals

If the authenticated user has permissions to request document approvals from specified assignees, the document resource will advertise a link with a @rel value of approvals. Additionally, it will return Approval elements containing details about the requester, along with a list of Assignments elements that provide information on the assigned approvers and other relevant details.

For more information on approvals operations, please visit Document Approvals.

Lock

Every document has a locking mechanism attached to it. If the authenticated user has permissions to lock a document, the document resource will advertise a link with a @rel value of lock, which can be used to lock the document to prevent others from modifying it.

If a document is locked, the document resource will not return a @rel value of lock link; instead, it returns the lock elements containing the lock details. Only individuals with a LockType of exclusive, coAuthoring, and eSign, have specific permission to edit the locked file.

For more information on the lock operations, please visit Lock.

Updating document title and description

If the authenticated user is authorized to edit a document, the document resource will advertise a link with a @rel value of edit. To update document metadata, submit a PUT request to this edit URI with the editable fields of the document.

Note that if the document is locked by another user, this operation will fail with a 409 Conflict.

Example

In this example, we first need to send a GET request to the edit URI advertised in the document resource.

Request

GET /files/documents/123/edit HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document"
    description="My Document description">
        <link rel="parent" href="..." />
</document>

Request

The user then updates the title and description attributes in the editable document resource and sent a PUT request back to the server.

PUT /files/documents/123/edit HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document is awesome"
    description="This is my document">
        <link rel="parent" href="..." />
</document>

Response

If successful, this operation will return a 202 Accepted, with a link header giving the location of the updated document.

HTTP/1.1 202 Accepted
Link: </files/documents/123>;rel="parent"

If a document with the same title and the same extension already exists within the folder, you will receive a 409 Conflict.

Once the document is updated, the document resource will return a new actor elements with a @rel value of updated-by.

Request

Sent a GET request to the document's self URI to get the updated document resource.

GET /files/documents/123 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Last-Modified: Thu, 04 Dec 1986 12:45:26 GMT
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document is awesome" mimetype="application/..." description="This is my document" extension="docx">
        <link rel="self" href=".../files/documents/1" />
        ... other document elements ...
        <actor name="Ian Cooper" email="ian.cooper@example.com" rel="owner">
            <link>...other actor links elements...</link>
        </actor>
        <actor name="Ian Cooper" email="ian.cooper@example.com" rel="updated-by">
            <link>...other actor links elements...</link>
        </actor>
</document>

This response uses the standard error codes and returns standard response headers.

Moving a document

The document resource supports moving a document to a new location, whether to a different workspace or a different part of the user's folder structure. If the authenticated user has a permission to move a document, the document resource will advertise a link with a @rel value of move. Note that moving a document also moves its metadata, including comments, activity history, and versions. The document ID remains the same, but it may change who has access to this document. If a document has approval request, moving it to a different workspace will remove the approval request.

Since moving is actually an edit operation, the @href for this action is the same as the @href for editing a document; links with a @rel value of edit. To move a document, sent a PUT request to the edit URI, with the new @href value of the @rel parent that is pointing to the new parent folder.

Example

In this example, the current document self URI is .../files/documents/1, and the parent URI is .../files/folders/2.

The user wants to move this document to a new parent with a self URI of .../files/folders/3.

Request

Sent a GET request to the document's edit URI to get the editable document resource.

GET /files/documents/1/edit HTTP/1.1
Accept: application/vnd.huddle.data+xml

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document"
    description="My Document is awesome">
        <link rel="parent" href="https:/files/folders/2" />
</document>

Request

The user then updates the @rel parent link, setting the @href to the URI of the new parent folder, and sent a PUT request back to the server.

PUT /files/documents/1/edit HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document"
    description="My Document is awesome">
        <link rel="parent" href="https:/files/folders/3" />
</document>

Response

If successful, the server will respond with a 202 Accepted and provides a link header with a @rel value of parent pointing to the document being moved, where user can monitor the value of the processingStatus element.

HTTP/1.1 202 Accepted
Content-Type: application/vnd.huddle.data+xml
Link: </files/documents/1>;rel="parent"

If a document with the same title and the same extension already exists within the folder, you will receive a 409 Conflict.

The user can monitor the value of the processingStatus elements to determine the status of the move operation by sending a GET request to the document's self URI. When the processingStatus elements is equal to Moving it means that the operation is still ongoing. When the operation is completed the processingStatus elements assumes the value is Complete. While the document is moving, it is not possible to download its content, and a 409 Conflict will be returned if a client attempts to do so.

Example of a moving document:

<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document" mimetype="application/..." description="My Document Descriptions" extension="docx">
        <link rel="self" href=".../files/documents/1" />
        ... other document elements ...
        <processingStatus>Moving</processingStatus>
</document>

Creating a new version of a document

The document resource supports creating a new version of a document. If the authenticated user has a permission to create a new version, the document resource will advertise a link with a @rel value of create-version.

To create a new version, sent a POST request to the create-version URI with either an empty body or a document version representation (see example below). The document version consists of title, description, mimeType and extension attributes. If these attributes are omitted, the previous version's title, description, mimeType, and extension values are used.

If the document is locked by another user, this operation will fail with a 409 Conflict response, which will include information about the lock. To ensure that no one else creates a new version or changes the content of the document while you are creating a new version, you should lock the document before performing this operation as described in the lock section.

The type of lock (either Exclusive or CoAuthoring) has an impact on how these versions are managed against the document. With an Exclusive lock, each time you create a version and upload associated content, the document is immediately updated and visible to all permitted users. With a CoAuthoring lock, the versions are stored privately and do not affect the document until a Version Promotion is invoked. In this scenario, members of the CoAuthoring lock can retrieve and download these versions (provided the requests originate from the same user that acquired the lock), but cannot generate previews.

Properties

Name Description
title The title of the document (optional)
description The description of the document (optional)
versionNote A note for the version (optional)
extension A extension for the document (optional but recommended) It helps identify duplicate file names
mimeType The MIME type of the document (optional)

Example

Request

The current version of the document is version 1. The user wants to create a new version of the document. Sent a POST request with an empty body to the document's create-version URI to create a new version of the document.

POST /files/documents/12345/version HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+xml
Link: </files/documents/1>;rel="parent"
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document" mimetype="application/vnd.openxmlformats-officedocument.wordprocessingml.document" description="My Document Descriptions" extension="docx">
        <link rel="upload" href=".../files/uploads/562eafc7-3d01-4651-9541-94acd1dad91e" />
        ... other document elements ...
        <version>2</version>
        <size>0</size>
        <updated>2025-02-28T03:22:50.753Z</updated>
        <created>2025-02-27T02:41:53.56Z</created>
        <processingStatus>Complete</processingStatus>
</document>

Request

The current version of the document is version 2. The user wants to create a new version of the document with new title and descriptions. Sent a POST request with documentVersion representation to the document's create-version URI to create a new version of the document.

POST /files/documents/12345/version HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<documentVersion xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    title="My Document V3" mimetype="application/vnd.openxmlformats-officedocument.wordprocessingml.document" description="This is the 3rd version of the document" extension="docx" />

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+xml
Link: <.../files/documents/1>;rel="parent"
<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document V3" mimetype="application/vnd.openxmlformats-officedocument.wordprocessingml.document" description="This is the 3rd version of the document" extension="docx" versionNote="Document note"/>
        <link rel="upload" href=".../files/uploads/562eafc7-3d01-4651-9541-94acd1dad91e" />
        ... other document elements ...
        <version>3</version>
        <size>0</size>
        <updated>2025-02-28T03:22:50.753Z</updated>
        <created>2025-02-27T02:41:53.56Z</created>
        <processingStatus>Complete</processingStatus>
</document>

If successful, the server will respond with a 201 Created, and the newly created document resource will advertise a link with a @rel value of upload for uploading the content of the document. For information on uploading a document operation, please visit Uploading Documents. Until new binary content is uploaded, the document resource will not advertise a @rel value of content. Earlier versions of document content will still be accessible through the VersionHistory resource.

If extension is provided on the POST request, the conflict check only applies to documents with the same title and same extension. A document with the same title but a different extension will not cause a 409 Conflict.

If extension is not provided on the POST request, the conflict check applies to all documents in the folder, regardless of extension. A document with the same title but a different extension will cause a 409 Conflict.

This response uses the standard error codes and returns standard response headers.

Difference Between Document Versions

If a user has enabled the Word Comparison features on their account and in the workspace where the document resides, and there is more than one document version, the document resource will advertise a link with a @rel value of difference-previous-version. When this feature is enabled, the user can compare the current document version with its previous version, with differences highlighted and a statistical summary of those difference. This feature is to help users who are collaborating on a Microsoft Word document to easily identify what has changed in the latest version, when compared to a previous version.

Note, only the workspace manager can enable or disable this feature for a workspace, and it is currently available only for Microsoft Word documents.

For more information on differences between document versions, please visit Document Version Difference.

Version Promotion

When versions are created for a document that is currently locked for CoAuthoring, they are not automatically applied to the document - meaning they are not visible unless the user is a member of the lock, and the request comes from the same user that the lock was taken in. For these versions to be applied to the document, they must be Promoted. It is only currently possible to promote the most recent save made during a particular CoAuthoring lock.

If the authenticated user has a permission to promote a version, the document resource will advertise a link with a @rel value of promote-latest. A POST to this URI with an empty request body will take the most recent version uploaded since the CoAuthoring' lock was taken and make that as the Latest Version for the document.

Example

Request

POST /files/documents/12345/promote/latest HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If the operation is successful, it will return a representation of the updated document resource, along with a Location header pointing to the document resource.

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: /files/documents/12345/
{
  "title": "document title",
  "description": "document description",
  "links": [
    {
      "rel": "self",
      "href": "..."
    }
    "...other links..."
  ]
  "...other document elements..."
}

If no promotion occurred (i.e. there wasn't a version created during the lifetime of the 'CoAuthoring' lock that required promotion), a 204 No Content response will be returned.

This response uses the standard error codes and returns standard response headers.

Deleting a document

The document resource supports deleting a document. If the authenticated user has a permission to delete a document, the document resource will advertise a link with a @rel value of delete. To delete the document, issue a DELETE request to the delete URI.

Example

Request

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

Response

If successful, the server will responds with a 200 OK, and provides a link header with a @rel value of parent folder.

HTTP/1.1 200 OK
Link: <.../files/folders/123>;rel="parent"

Copying a document

The document resource supports making a copy of a document. If the authenticated user has a permission to copy a document, the document resource will advertise a link with a @rel value of copy. Documents can be copied to the same folder, to another folder within the workspace, or to a folder in another workspace. Note that only the latest version of the document will be copied. It does not copy previous document versions, comments, activity history, and approvals.

When a document is copied, the copy retains the same title as the original. However, if a document with the same title and description already exists in the target folder, the copied document will be suffixed with a number. For example, a copy of the document My document.doc would be named My document (1).doc.

When making a POST request to the Copy Document endpoint, user should include a link to the target folder in the POST body of the request (see Example below).

Example

Request

To copy a document, sent a POST request to the copy URI with a link to the target folder.

POST /files/documents/123/copy HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<copyDocument>
    <targetFolder>
        <link rel="self" href=".../files/folders/456" />  
    </targetFolder>
</copyDocument>
Response

If successful, the server will responds with a 201 Created, and provides a link of the new document in the Location header.

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+xml
Location: /files/documents/789

Error Response

Case Response
Document does not exist 404 Not Found
Document is deleted 410 Gone
Document is in a moving state 409 Conflict
Document is in a processing state 409 Conflict
Document is in an error state 409 Conflict
Target folder not provided 400 Bad Request
Target folder does not exist 400 Bad Request
Target folder is deleted 410 Gone
User does not have permission to copy documents from the source folder 403 Forbidden
User does not have permission to create documents in the target folder 403 Forbidden
User does not have permission to publish a document 403 Forbidden
User does not have permission to unpublish a document 403 Forbidden

Retrieving a document thumbnail

For certain file types, a thumbnail is automatically and asynchronously created when the file is uploaded. This includes the most common image and video MIME types.

If the document version’s MIME type is supported, the document resource will return a thumbnails element containing a thumbnail child elements that contains a link with a @rel value of content. A GET request to the thumbnail's content URI will return the thumbnail content. If thumbnails do not exist, the server will response with a 404 not Found.

Example: A document resource with a thumbnail.

<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document" mimetype="application/..." description="My Document Descriptions" extension="docx">
        <link rel="self" href=".../files/documents/1" />
        ... other document elements ...
        <thumbnails>
            <thumbnail type="medium">
                <link rel="content" href='.../files/documents/versions/123/thumbnails/medium/content' />
            </thumbnail>
        </thumbnails>
</document>

Example: Getting the content of a thumbnail.

Request

Sent a GET request to the document's thumbnails content URI.

GET /files/documents/versions/123/thumbnails/medium/content; HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If the thumbnail exists, the server will response with a 200 OK and thumbnail content.

HTTP/1.1 200 OK
Cache-Control: private, max-age=600
Content-Type: image/jpeg
Content-Length: 930
A stream that makes up the image...

Tags

This resource supports adding and removing tags from a document. If the authenticated user has a permission to create a document's tag, the document resource will advertise a link with a @rel value of tag.

Example: Adding a tag to a document.

Request

Sent a POST request to the document's tags URI with the tag value in the request body.

POST /files/documents/1/tags HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<tag>
    <value>documentation</value>
</tag>

Response

If successful, the server will respond with a 201 Created and provides a link of the new tags in the Location header.

HTTP/1.1 201 OK
Content-Type: application/vnd.huddle.data+xml
Location: /files/documents/1/tags/documentation

If the supplied tag already existed, the server will response with a 409 Conflict.

Once the tag is added, the document resource will return a new tag element's link with a @rel value of self.

Example: Updated document resource with the newly added tags.

<document xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    title="My Document is awesome" mimetype="application/..." description="This is my document" extension="docx">
        <link rel="self" href=".../files/documents/1" />
        ... other document elements ...
        <tags>
            <tag value="documentation">
                <link rel="self" href="...files/documents/7392/tags/documentation" />
            </tag>
        </tags>
</document>

Example: Removing a tag from a document.

Request

Send a DELETE request to the tag element's @rel="self" URI that the user wishes to remove.

DELETE /files/documents/1/tags/documentation HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

If successful, the server will responds with a 204 Accepted, and remove the tag elements from the document resource.

HTTP/1.1 204 No Content
Content-Type: application/vnd.huddle.data+xml

Pins

The document resource supports pinning a document to a workspace. If the authenticated user has a permission to pin a document, the document resource will advertise a link with a @rel value of pin. A pinned document is displayed at the top of the workspace's Pinned files and folders, making it easier to reach. When a document is pinned, the document resource will not return a @rel value of pin link; instead, it return the pin elements containing the pin details.

Comments

For more information on retrieving a collection of comments, creating a comment, or deleting a comment from a document, see Document Comments.

Tracking Document Changes

For more information on retrieving a collection of changes made to a document, or to manually create a document changes, see Audit Trail.

Sharing a document

If the authenticated user has a permission to share a document, the document resource will advertise a link with a @rel value of share. For more information on sharing a document, see Sharing.

Previews

If previews are supported for the document's file type, the document resource will advertise a link with a @rel value of previews. For more information on document previews, see Previews.

Last viewed version of document

When a user views a document, the action is recorded in the document's activity trail. Sending a GET request to the link with a @rel value of last-viewed will return the details of the last document version viewed by the user. For more information, see Document Last Viewed.

Syntax

Examples

A locked document retrieved by the owner of the lock

<document itemType="Document" title="My Document">
  <link rel="self" href="..." />
  ... other document elements ...
  <lock>
    <link rel="self" href="..." />
    <link rel="delete" href="..." />
    <link rel="parent" href="..." />
    <actor name="Peter Gibson" rel="owner">
      <link rel="self" href="..." />
      <link rel="avatar" href="..." type="image/jpg" />
      <link rel="alternate" href="..." type="text/html" />
    </actor>
    <lockDate>2007-10-10T09:02:17Z</lockDate>
  </lock>
</document>

A locked document retrieved by a user that doesn't own the lock

<document itemType="Document" title="My Document">
  <link rel="self" href="..." />
  ... other document elements ...
  <lock>
    <link rel="self" href="..." />
    <actor name="Peter Gibson" email="peter.gibson@example.com" rel="owner">
      <link rel="self" href="..." />
      <link rel="avatar" href="..." type="image/jpg" />
      <link rel="alternate" href="..." type="text/html" />
    </actor>
    <lockDate>2007-10-10T09:02:17Z</lockDate>
  </lock>
</document>

Properties

Name Description
@title The title of the document.
@description The description of the document.
lock Present if the document is locked.
size The size of the document expressed in bytes.
version The version of the document.
created Document created date.
updated Document updated date.
pinned Whether the document is pinned.
processingStatus
  • Complete: the document is not processing
  • Processing: the document is empty or an upload is in progress
  • Moving: the document is being moved in another location
  • Error: a processing error occurred
  • Uploaded: The document has had all its content upload and has some final processing processing before it will be marked as complete
views Depreciated field
publications scope none = not published
approval The approval for the document if applicable. This currently only contains the approval status.
pin Present if the document is pinned.

Link relations

Name Description Methods
content The link is returned if the document contains binary content and user is permitted to download the document content. The type attribute specifies the file's MIME type, and the title attribute represents the filename. GET
latest-content The link is returned if user has enabled the Office for Browser Integration feature in the workspace settings and is permitted to open the document in Microsoft Office Online, either for editing or read-only access. N/A
print-preview To add an 'opened print preview' audit trail to the document's activity. The link is returned if the user has enabled download and print features in the workspace settings. POST
integrations The link is returned if the user has enabled the Office for Browser Integration feature in the workspace settings. A GET request to this URI will return the OfficeOnline permission summary resource. GET
parent The folder which contains this document. The title attribute is the name of the folder. GET
paged-parent-folder The folder which contains this document. The title attribute is the name of the folder. GET
parent-folder The folder which contains this document. The title attribute is the name of the folder. GET
bulk-delete The link is returned if user is permitted to delete multiple documents in one request. For more info on this operation, see Bulk Delete POST
edit To update the document details. PUT
create-version To create a new version of the document. POST
promote-latest The link is returned if there is a version uploaded during the current CoAuthoring lock and user is permitted to promote that version to be the latest version of the document. POST
lock To lock or unlock a document. Locking a document will returns the Lock resource. POST, DELETE
publish To publish a document, making it accessible either publicly or privately. POST
unpublish The link is returned if a document is published and user is permitted to unpublish the document. DELETE
delete To delete a document. DELETE
move To move a document to a different folder or workspace. Note that this URI is the same as edit URI. PUT
copy To copy a document. POST
self The current URI of this document. GET
last-viewed To retrieve a details of the last document version viewed by a user. GET
version-history The link is returned if the document has more than one versions and user is permitted to retrieve the collection of versions. GET
upload To change the binary content of the document. POST
comments To retrieve a list of existing comments on a document, create a new comment, or delete a comment. The count attribute is the total number of comments for the document. GET, POST, DELETE
comments-paged DELETE
approvals If existed, user can use this URI to retrieve a collection of approval assignments for a document. It returns the DocumentApprovals resource. GET
viewed To add a 'Viewed' audit trail to the document's activity. POST
tasksUri To retrieve, create, or delete tasks associated with a document. GET, POST, DELETE
permissions To retrieve a list of users who have been granted permissions to read or edit a document. GET
share To share a document. POST
audittrail To retrieve the audit trail or activity history of a document. GET
current-lock To retrieve the cureent document's lock details. GET
previews The link is returned if if the document's file type supports preview. GET
alternate Huddle's custom scheme URI follows the format: huddle://relative_self_link, allowing external applications to register as handlers for the link and retrieve the document when clicked. N/A
shortlink A shortened link to the document on the Huddle website. N/A
recipients To retrieve the details of document's notification recipients. GET
make-offline The link is returned if user has enabled the Office ofiline GET, POST, DELETE
tags To add or remove a document's tag. POST, DELETE
pin To pin a document to the workspace pins view or unpin it from the workspace pins view. POST, DELETE
difference-previous-version To compare between current version and previous version of a document. POST

Schema

start = document

document = element h:document {
  attribute itemType {xsd:string},
  attribute title {xsd:string},
  attribute description {xsd:string}?,
  (empty | link + |
	(
	  link+,
    actor+,
	  lock?,
    element h:size {xsd:unsignedLong},
    element h:version {xsd:unsignedInt},
    element h:created {xsd:dateTime},
    element h:updated {xsd:dateTime},
    element h:processingStatus {"Complete"|"Error"|"Moving"|"Processing"|"Uploaded"},
    element h:views {xsd:unsignedInt},
    thumbnails?
    pin?,
	))
}

lock = element h:lock {
  link+,
  actor
}

pin = element h:pin {
  link+,
  actor,
  element h:pinnedDate {xsd:dateTime},
}

thumbnails = element h:thumbnails{
  thumbnail+
}

thumbnail = element h:thumbnail{
  link+
}
Classic
Clone this wiki locally