Note

This API is obsolete and has moved to DocumentApprovals.

This page is retained as a legacy reference for the original DocumentApprovals resource and should remain internally consistent for teams maintaining or reviewing older integrations.

Legacy APIs

Summary

It is possible for a user to request approval of a Document resource from a set of specified assignees. The DocumentApprovals resource represents this collection of approval assignments for a given document.

Operations

Method	Path	Purpose	Details
`GET`	`/files/documents/{documentId}/approvals`	Retrieving approvals for a document	Jump
`POST`	`/files/documents/{documentId}/approvals/request`	Creating or updating a document approval	Jump
`POST`	`/files/documents/{documentId}/approvals/updateassignees`	Updating document approval assignees	Jump
`POST`	`/files/documents/{documentId}/approvals/assignment`	Updating document approval assignment status	Jump

Retrieving approvals for a document

The document resource will advertise a link with a @rel value of approvals. To retrieve the document approvals, send a GET request to the approvals URI. The server will return a DocumentApprovals resource.

Example

Request

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

<documentApprovals xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/files/documents/123/approvals" />
  <link rel="updateassignees" href="/files/documents/123/approvals/updateassignees" />
  <link rel="approvalrequest" href="/files/documents/123/approvals/request" />
  <link rel="parent" href="/files/documents/123" />

  <status>Open</status>
  <dueDate>2007-10-10T09:02:17Z</dueDate>

  <actor name="Jimmy Snake" email="[email protected]" rel="requester">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>

  <assignments>
    <assignment>
      <link rel="self" href="..." />
      <actor name="Peter Gibson" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Complete</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:02:17Z</completed>
    </assignment>

    <assignment>
      <link rel="self" href="..." />
      <link rel="edit" href="..." />
      <actor name="Jimmy Snake" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Open</status>
      <created>2007-10-10T09:02:17Z</created>
    </assignment>
  </assignments>
</documentApprovals>

Updating document approval assignees

The DocumentApprovals resource will advertise a link with a @rel value of updateassignees. This allows you to replace the approval's assignee list by posting the full list to that link.

The request may optionally include an X-Allow-Invalid-Reviewers header, which should be true or false (case-insensitive). It determines whether the update-assignees request should fail with a 400 Bad Request if any of the users cannot be added to the list of approvers, or return a 200 OK to indicate that the request was sent to as many users as possible.

Example

Request

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

<updateApprovalAssignees>
  <message>Can you all approve this please?</message>
  <assignee href="..." />
  <assignee href="..." />
</updateApprovalAssignees>

Response

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

<documentApprovals xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/files/documents/123/approvals" />
  <link rel="updateassignees" href="/files/documents/123/approvals/updateassignees" />
  <link rel="approvalrequest" href="/files/documents/123/approvals/request" />
  <link rel="parent" href="/files/documents/123" />

  <status>Open</status>
  <dueDate>2007-10-10T09:02:17Z</dueDate>

  <actor name="Jimmy Snake" email="[email protected]" rel="requester">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>

  <assignments>
    <assignment>
      <link rel="self" href="..." />
      <actor name="Peter Gibson" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Complete</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:02:17Z</completed>
    </assignment>

    <assignment>
      <link rel="self" href="..." />
      <link rel="edit" href="..." />
      <actor name="Jimmy Snake" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Open</status>
      <created>2007-10-10T09:02:17Z</created>
    </assignment>
  </assignments>
</documentApprovals>

Failed Response

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.huddle.data+xml

<updateApprovalAssigneesFailure>
  <reason>The reason was...</reason>
  <link rel="assignee" href="..." />
  <link rel="assignee" href="..." />
</updateApprovalAssigneesFailure>

Request With Optional Header

POST /files/documents/123/approvals/updateassignees HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
X-Allow-Invalid-Reviewers: true

<updateApprovalAssignees>
  <message>Can you all approve this please?</message>
  <assignee href="..." />
  <assignee href="..." />
</updateApprovalAssignees>

Creating or updating a document approval

The DocumentApprovals resource will advertise a link with a @rel value of approvalrequest. This allows you to create a new document approval, or, if one already exists, update its due date and assignees.

The request may optionally include an X-Allow-Invalid-Reviewers header, which should be true or false (case-insensitive). It determines whether the request should fail with a 400 Bad Request if any of the users cannot be added to the list of approvers, or return a 200 OK to indicate that the request was sent to as many users as possible.

Example

Request

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

<approvalRequest>
  <message>Can you all approve this please?</message>
  <assignee href="..." />
  <assignee href="..." />
  <dueDate>2012-10-10T09:02:17Z</dueDate>
</approvalRequest>

Response

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

<documentApprovals xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/files/documents/123/approvals" />
  <link rel="updateassignees" href="/files/documents/123/approvals/updateassignees" />
  <link rel="approvalrequest" href="/files/documents/123/approvals/request" />
  <link rel="parent" href="/files/documents/123" />

  <status>Open</status>
  <dueDate>2012-10-10T09:02:17Z</dueDate>

  <actor name="Jimmy Snake" email="[email protected]" rel="requester">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>

  <assignments>
    <assignment>
      <link rel="self" href="..." />
      <actor name="Peter Gibson" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Complete</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:02:17Z</completed>
    </assignment>

    <assignment>
      <link rel="self" href="..." />
      <link rel="edit" href="..." />
      <actor name="Jimmy Snake" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Open</status>
      <created>2007-10-10T09:02:17Z</created>
    </assignment>
  </assignments>
</documentApprovals>

Updating approval assignment status

If the authenticated user has a document approval assignment, a link with rel edit will be displayed on the relevant assignment. Send a POST request to this URI to change the status of the assignment. A GET request for this edit resource is not currently implemented.

Example

Request

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

<assignment>
  <status>Rejected</status>
</assignment>

Name	Description
`status`	The desired state of the assignment. Supported values are `Complete` and `Rejected`.

Response

If successful, the request will return a 200 OK with the updated DocumentApprovals resource.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Content-Location: /files/documents/123/approvals

<documentApprovals xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/files/documents/123/approvals" />
  <link rel="parent" href="/files/documents/123" />
  <link rel="updateassignees" href="/files/documents/123/approvals/updateassignees" />
  <link rel="approvalrequest" href="/files/documents/123/approvals/request" />

  <status>Open</status>
  <dueDate>2007-10-10T09:02:17Z</dueDate>

  <actor name="Jimmy Snake" email="[email protected]" rel="requester">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>

  <assignments>
    <assignment>
      <link rel="self" href="..." />
      <actor name="Peter Gibson" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Complete</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:02:17Z</completed>
    </assignment>

    <assignment>
      <link rel="self" href="..." />
      <actor name="Jimmy Snake" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Rejected</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:05:17Z</completed>
    </assignment>
  </assignments>
</documentApprovals>

Syntax

Example

Approvals with due date

<documentApprovals xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/files/documents/123/approvals" />
  <link rel="parent" href="/files/documents/123" />
  <link rel="updateassignees" href="/files/documents/123/approvals/updateassignees" />
  <link rel="approvalrequest" href="/files/documents/123/approvals/request" />

  <status>Open</status>
  <dueDate>2007-10-10T09:02:17Z</dueDate>

  <actor name="Jimmy Snake" email="[email protected]" rel="requester">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>

  <assignments>
    <assignment>
      <link rel="self" href="..." />
      <actor name="Peter Gibson" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Complete</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:02:17Z</completed>
    </assignment>

    <assignment>
      <link rel="self" href="..." />
      <actor name="Jimmy Snake" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Open</status>
      <created>2007-10-10T09:02:17Z</created>
    </assignment>
  </assignments>
</documentApprovals>

Approvals with no due date

<documentApprovals xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/files/documents/123/approvals" />
  <link rel="parent" href="/files/documents/123" />
  <link rel="updateassignees" href="/files/documents/123/approvals/updateassignees" />
  <link rel="approvalrequest" href="/files/documents/123/approvals/request" />

  <status>Open</status>

  <actor name="Jimmy Snake" email="[email protected]" rel="requester">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>

  <assignments>
    <assignment>
      <link rel="self" href="..." />
      <actor name="Peter Gibson" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Complete</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:02:17Z</completed>
    </assignment>

    <assignment>
      <link rel="self" href="..." />
      <actor name="Jimmy Snake" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Open</status>
      <created>2007-10-10T09:02:17Z</created>
    </assignment>
  </assignments>
</documentApprovals>

Approvals with open assignment for the authenticated user

<documentApprovals xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/files/documents/123/approvals" />
  <link rel="parent" href="/files/documents/123" />
  <link rel="updateassignees" href="/files/documents/123/approvals/updateassignees" />
  <link rel="approvalrequest" href="/files/documents/123/approvals/request" />

  <status>Open</status>
  <dueDate>2007-10-10T09:02:17Z</dueDate>

  <actor name="Jimmy Snake" email="[email protected]" rel="requester">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>

  <assignments>
    <assignment>
      <link rel="self" href="..." />
      <actor name="Peter Gibson" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Complete</status>
      <created>2007-10-10T09:02:17Z</created>
      <completed>2007-10-10T09:02:17Z</completed>
    </assignment>

    <assignment>
      <link rel="self" href="..." />
      <link rel="edit" href="..." />
      <actor name="Jimmy Snake" email="[email protected]" rel="assignee">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
      <status>Open</status>
      <created>2007-10-10T09:02:17Z</created>
    </assignment>
  </assignments>
</documentApprovals>

Properties

Name	Description
`status` (for the `documentApprovals` element)	Present if the document has approval assignments. The value is `Open` if there are still outstanding assignments, or `Complete` if all assignments are completed.
`dueDate`	Present if the document approval has a completion date.
`actor`	The requester for the approval. This actor has `rel="requester"`.
`assignments`	The container for the document's approval assignments.
`assignment`	An assignment represents a document approval request for one assignee.
`status` (for the `assignment` element)	The assignment state. Values shown by this legacy contract are `Open`, `Complete`, and `Rejected`.
`created`	The date and time at which the assignment was created.
`completed`	Present if the assignment status is `Complete` or `Rejected`. It is the date and time at which the assignment was completed.

Link relations

Name	Description	Methods
`self`	The current URI of this `DocumentApprovals` resource.	`GET`
`parent`	Retrieves the document that this resource belongs to.	`GET`
`updateassignees`	Replaces the assignee list for the approval on the document.	`POST`
`approvalrequest`	Creates a new approval request or updates the existing approval's due date and assignees.	`POST`
`edit` (for the `assignment` element)	If the authenticated user has an open approval assignment, this link can be used to update the status of that assignment. This link is present on the relevant assignment only while it is editable.	`POST`

Schema

The schema below is illustrative and partial. It is intended to describe the legacy DocumentApprovals shape used in the examples on this page, not to exhaustively define every optional child element or link variant.

start = documentApprovals

documentApprovals = element h:documentApprovals {
  link+,
  element h:status {"Complete"|"Open"}?,
  element h:dueDate {xsd:dateTime}?,
  actor?,
  element h:assignments { assignment* }
}

assignment = element h:assignment {
  link+,
  actor?,
  element h:status {"Open"|"Complete"|"Rejected"},
  element h:created {xsd:dateTime},
  element h:completed {xsd:dateTime}?
}

DocumentApprovalsRetired - Huddle/huddle-apis GitHub Wiki

Note

Summary

Operations

Retrieving approvals for a document

Example

Request

Response

Updating document approval assignees

Example

Request

Response

Failed Response

Request With Optional Header

Creating or updating a document approval

Example

Request

Response

Updating approval assignment status

Example

Request

Response

Syntax

Example

Approvals with due date

Approvals with no due date

Approvals with open assignment for the authenticated user

Properties

Link relations

Schema

⚠️ GitHub.com Fallback ⚠️

DocumentApprovalsRetired - Huddle/huddle-apis GitHub Wiki

Note

Summary

Operations

Retrieving approvals for a document

Example

Request

Response

Updating document approval assignees

Example

Request

Response

Failed Response

Request With Optional Header

Creating or updating a document approval

Example

Request

Response

Updating approval assignment status

Example

Request

Response

Syntax

Example

Approvals with due date

Approvals with no due date

Approvals with open assignment for the authenticated user

Properties

Link relations

Schema

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️