DocumentComments - Huddle/huddle-apis GitHub Wiki

Summary

The DocumentComments resource is the full (unpaged) collection of comments for a document. It is implemented on the Files API at /files/documents/{documentId}/comments.

For keyset-paged comments (default page size, next/prev links), use Paged document comments (GET /files/documents/{documentId}/pagedcomments).

Operations

Method Path Purpose Details
GET /files/documents/{documentId}/comments Retrieving document comments Jump
POST /files/documents/{documentId}/comments Creating a new comment Jump
POST /files/documents/{documentId}/comments Mentioning users and teams within comments Jump
DELETE /files/documents/{documentId}/comments/{commentId} Deleting a comment Jump

Retrieving document comments

The document resource advertises a link with rel="comments". GET that URI returns a documentComments representation.

Behaviour (Files API):

  • Comment content in the response is produced with GetContentWithNoMarkDownUserLinks() (markdown-style user links in headers are normalised for display; do not expect raw [Display](url) text in GET the same as in POST).
  • Each comment includes actor elements for the owner only (rel="owner"). Mentioned users are not listed as extra actors on this collection resource.
  • link rel="delete" on a comment is present only when the current user may delete that comment.

Example

Request

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

Typical XML serialisation order is comments first, then collection-level link elements; exact ordering can depend on the codec.

<documentComments xmlns="http://schema.huddle.net/2011/02/">
  <comments>
    <comment>
      <link rel="self" href="/files/documents/123/comments/987" />
      <link rel="delete" href="/files/documents/123/comments/987" />
      <content>This is a comment for the document</content>
      <created>2007-10-10T09:02:17Z</created>
      <version>12</version>
      <actor name="Peter Gibson" email="[email protected]" rel="owner">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpeg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
    </comment>
    <comment>
      <link rel="self" href="/files/documents/123/comments/986" />
      <content>This is another comment for the document</content>
      <created>2007-10-10T09:02:17Z</created>
      <version>12</version>
      <actor name="Jimmy Snake" email="[email protected]" rel="owner">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpeg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
    </comment>
  </comments>
  <link rel="self" href="/files/documents/123/comments" />
  <link rel="parent" href="/files/documents/123" />
  <link rel="create" href="..." />
</documentComments>

Creating a new comment

If the user may add comments, the collection includes rel="create" pointing at the same comments URI. POST with a comment body.

Example

Request

POST /files/documents/12345/comments HTTP/1.1
Host: api.huddle.example
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<comment>
  <content>This is a comment for the document</content>
  <replytoid>message_id</replytoid>
</comment>

Properties

Name Description
content Required. Length 1–10000 characters (CreateCommentCommand validation).
replytoid Optional. Id of the message you are replying to.
approval Optional. When commenting in an approval context, Complete or Rejected (case-insensitive); invalid values yield an error.

Response

201 Created with a full documentComments representation (same shape as GET).

400 Bad Request can occur for invalid approval, validation failures, or SameTextUsedForDifferentLinkException (ambiguous markdown links) with error code Ambiguous Links.

Mentioning users and teams within comments

You can mention users, teams, or everyone using markdown-style links in content, for example:

[Display name](https://host/.../users/{id}), [Team](https://host/.../teams/{id}), or the product’s “everyone” link pattern the server recognises.

Only users who can read the document are notified. Mentions do not add subscribers to the document beyond notification.

Example request

POST /files/documents/12345/comments HTTP/1.1
Host: api.huddle.example
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<comment>
  <content>
    Hey [John Smith](https://my.huddle.example/users/111), this is a comment
    for the document. Also [Team A](https://my.huddle.example/teams/222).
  </content>
</comment>

Response

201 Created with the updated documentComments collection. The saved comment’s content in that response is still passed through the same display pipeline as GET (plain display text, not necessarily identical to the submitted markdown). Mentioned users are not exposed as separate actor entries on this resource—only the owner actor appears per comment.

Deleting a comment

DELETE the comment’s self / delete URI when delete is advertised.

Example

Request

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

Response

HTTP/1.1 204 No Content

Syntax

Example

<documentComments xmlns="http://schema.huddle.net/2011/02/">
  <comments>
    <comment>
      <link rel="self" href="/files/documents/123/comments/987" />
      <link rel="delete" href="/files/documents/123/comments/987" />
      <content>This is a comment for the document</content>
      <created>2007-10-10T09:02:17Z</created>
      <version>12</version>
      <actor name="Peter Gibson" email="[email protected]" rel="owner">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpeg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>
    </comment>
  </comments>
  <link rel="self" href="/files/documents/123/comments" />
  <link rel="parent" href="/files/documents/123" />
  <link rel="create" href="..." />
</documentComments>

Link relations

Name Description Methods
self This documentComments resource. GET
parent The document. GET
create Create a comment (POST). POST
delete Delete this comment (only if permitted). DELETE

Schema (informal)

documentComments = documentComments {
  comments { comment* },
  link+
}

comment = comment {
  link+,
  actor+,
  content,
  created,
  version,
  replytoid?,
  approval?
}

There is no actors wrapper element: multiple actors would be repeated <actor> siblings (in practice the list endpoint adds the owner only).

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