PagedDocumentComments - Huddle/huddle-apis GitHub Wiki

Summary

The DocumentComments resource represents the paged collection of comments for a specific document resource. Comments can have mentioned entities including users, teams and everyone.

Controlling Paging

Keyset pagination is a continuous loading technique to perform pagination which is more performant on large datasets. On each request the client is provided with a subset of the comments with a set of links to help navigate to the next or previous set of data. Therefore the client never makes an unbounded call to the API and data can be retrieved incrementally which improves the user experience.

The default paging for comments is to return the first 50 items sorted by its created date (with the most recent appearing first). The next and prev links are used to navigate through the pagination and bring the next/previous set of 50 comments.

Examples of pagination links

Link Description
rel="self" href="../documents/123/pagedcomments?fromCommentId=147" The current comment id is 147, this gets 50 comments from that id
rel="first" href="../documents/123/pagedcomments?size=50" First 50 comments
rel="next" href="../documents/123/pagedcomments?fromCommentId=147&direction=forwards&size=50" The current comment id is 147, this gets 50 comments from that id
rel="prev" href="../documents/123/pagedcomments?fromCommentId=147&direction=backwards&size=50" The current comment id is 147, this gets 50 comments before that id

Parameters

Name Description Methods Optional Default Notes
fromCommentId The first comment id of the current page set GET Yes 0
direction Determines which direction to get the paged data GET Yes forwards
size Number of items to retrieve on a page GET Yes 50 Maximum is 250
sort Sorts the comments by created date GET Yes descending (newest first) Ascending/Descending

Operations

Example

Request

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

Response

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

<documentComments xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="documents/123/pagedcomments" />
  <link rel="parent" href="documents/123" />

  <collection>
    <links>
      <link rel="prev" href="..." />
      <link rel="next" href="..." />
      <link rel="first" href="..." />
    </links>
    <items>
      <comment>
        <link rel="self" href="documents/123/pagedcomments/987" />
        <link rel="delete" href="documents/123/comments/987" />
        <content>Hey Everyone and John Smith could you help Team Comments and Jim Taylor with their work</content>
           <created>2007-10-10T09:02:17Z</created>
        <version>12</version>

        <actors>
          <actor name="Peter Gibson" email="[email protected]" rel="owner">
            <link rel="self" href="..." />
            <link rel="avatar" href="..." type="image/jpg" />
            <link rel="alternate" href="..." type="text/html" />
          </actor>
        </actors>
      </comment>

      <comment>
        <link rel="self" href="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/jpg" />
          <link rel="alternate" href="..." type="text/html" />
        </actor>
      </comment>
    </items>
  </collection>
  <queries>
    <query>
      <link href="documents/123/pagedcomments" rel="paging"/>
      <prompt>Enter paging choices</prompt>
      <data>
        <parameter name="fromCommentId" value="147" />
        <parameter name="size" value="50" />
      </data>
    </query>
  </queries>
</documentComments>

Included projections

@Mentions summary

When retrieving the comments, a projection query string can be added to the request URL in order to obtain additional information about the @mentioned, users and teams. Without the project the content will contain plain text without the @mentioned metadata to do the necessary substitutions.

The @mentions in the text are denoted by a unique identifier wrapped with square brackets. The identifiers are in the format of "resourcetype:resourceId" which the client will parse and search for the information with the list of actors or teams that is provided in the response. This provides greater flexiblity for the client to render or style the @mentions without changing the API response.

The alternate links for @mentions of everyone and teams are links to the teams page under the People tab.

Retrieving document comments with projection

You can retrieve enriched mentions by adding the mentions projection option as demonstrated below.

Example

Request

GET /documents/123/pagedcomments?projection=mentions HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

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

<documentComments xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="documents/123/pagedcomments?projection=mentions" />
  <link rel="parent" href="documents/123" />

  <collection>
    <links>
      <link rel="prev" href="..." />
      <link rel="next" href="..." />
      <link rel="first" href="..." />
    </links>
    <items>
      <comment>
        <link rel="self" href="documents/123/pagedcomments/987" />
        <link rel="delete" href="documents/123/comments/987" />
        <content>Hey [everyone:everyone] and [user:1] could you help [team:1]
  and [user:2] with their work</content>
        <created>2007-10-10T09:02:17Z</created>
        <version>12</version>
        <contentsubstitutions>
             <mention>
               <type>user</type>
               <key>user:1</key>
               <value>
                 <DisplayName>John Smith</DisplayName>
                 <link rel="self" href="..." />
                 <link rel="alternate" href="..." />
               </value>
             </mention>
             <mention>
               <type>user</type>
               <key>user:2</key>
               <value>
                 <DisplayName>Bob Smith</DisplayName>
                 <link rel="self" href="..." />
                 <link rel="alternate" href="..." />
               </value>
             </mention>
             <mention>
               <type>team</type>
               <key>team:1</key>
               <value>
                 <link rel="self" href="..." />
                 <link rel="alt" href="..." />
                 <name>The Media Team</sname>
               </value>
             <mention>
             <mention>
               <type>team</type>
               <key>everyone:everyone</key>
               <value>
                 <link rel="alt" href="..." />
               </value>
             <mention>
        </contentsubstitutions>
        <actor name="Peter Gibson" email="[email protected]" rel="owner">
          <link rel="self" href="..." />
          <link rel="avatar" href="..." type="image/jpg" />
          <link rel="alternate" href="..." type="text/html" />
        </actor>
      </comment>

      <comment>
        <link rel="self" href="documents/123/comments/986" />
        <content>This is another comment for the document</content>
        <created>2007-10-10T09:02:17Z</created>
        <version>12</version>

        <actors>
          <actor name="Jimmy Snake" email="[email protected]" rel="owner">
            <link rel="self" href="..." />
            <link rel="avatar" href="..." type="image/jpg" />
            <link rel="alternate" href="..." type="text/html" />
          </actor>
        </actors>
      </comment>
     </items>
     <queries>
      <query>
        <link href="documents/123/pagedcomments" rel="paging"/>
        <prompt>Enter paging choices</prompt>
        <data>
          <parameter name="fromCommentId" value="147" />
          <parameter name="size" value="50" />
        </data>
      </query>
    </queries>
  </collection>
</documentComments>

Error Responses

Case Response
Document does not exist 404 Not Found
User does not have permission to document 403 Forbidden
⚠️ **GitHub.com Fallback** ⚠️