Skip to main content

 Services

Web services from /about to /webhooks

find comments public

/comments/find [GET]

Description

This service returns a list of public comments using parameters to filter the results. The list of groups specified must be public groups. The most recent comments are returned first.

This service performs a search directly on the database and returns the corresponding comment instances as XML. Alternatively, an index search could provide better performance with the caveat that there can be a slight delay between a comment creation or update and its availability in the index.

Parameters

NameDescriptionRequiredTypeDefault value
groupsComma-separated list of group names the comments MUST belong toyesstrings
archivedIf true, include archived commentsnobooleanfalse
attachmentsThe attachments to include, can be none, context or allnoenumall
authorThe ID of the comments authornolong
contentsThe contents to include, can be none or allnoenumall
contextOnly return comments in this context, can be group, uri, allnoenumall
createdafterThe date time after which the comments were created e.g. 2010-10-25T12:26:00+10:00nodatetime
createdbeforeThe date time before which the comments were created e.g. 2011-08-25T10:20:00-04:00nodatetime
emailsThe email addresses to include, can be none or all  (all for administrators only)nobooleannone
labelsComma-separated list of label values – comment MUST have all (not recommended for filtering large data sets)nostring
moderatedIf true, include moderated (not accepted) commentsnobooleanfalse
pageThe page to loadnolong1
pagesizeThe number of results per pageno long1000
pathsThe context URI paths for the comments – MUST be URL encoded (comma-separated list with optional * suffix)nopaths
positionIf first, only the first (root) comment in a discussion is returned (might be faster when using paths)nostringany
returngroupsThe groups to return in the output, can be none, specifiednoenumnone or if multiple groups specified
statusesComma-separated list of statusesnostatus
titleThe title the comments MUST have (optional wildcard * suffix, use ** to escape)nostring
typeThe type the comments MUST have (optional wildcard * suffix, use ** to escape)nostring
typesComma-separated list of types the comment can have (empty string means no type)nostrings

Including all attachments, contents and returned groups can incur a performance penalty when loading large discussions. Some of the following parameters allow developers to control whether they are loaded and returned or not.

attachments

This parameter determines whether attachments are included in the response. Possible options are:

  • none – No attachment is to be included
  • context – Only include the context document or URL
  • all – Include all attachments

The context is usually the same for all comments within the same discussion.

contents

This parameter determines whether the contents of the individual comments are included in the response.

Possible options are:

  • none – The content is not to be loaded
  • all – Load the content of all comments

There is usually only one content of type text/plain when comments are entered through the user interface. However, it is possible to have contents with different media type when the comment has been created through the API.

returngroups

This parameter determines whether to return groups on to which the comments were posted.

Returning the group might be unnecessary if the client knows the group and the comments aren't shared.

Possible options are:

  • none – The groups are not to be loaded
  • specified – Load the content of all comments

statuses

A comma-separated list of task status or document status values.

Permission

This service can only list comments based on the groups that user have access. If the group is public, anyone can access it.

If the parameter emails is set to all, the permission is restricted to administrator only.

Response

This service returns a list of <comment> elements wrapped in a <comments> element as in the following example.

<comments>
  <comment id="234"
           contentrole="File Attachment"
           created="2012-03-08T12:34:00+10:00">
    <title>My thread</title>
    <content type="text/plain">Some text</content>
    <attachment>
      <uri id="189">...</uri>
    </attachment>
    <attachment fragment="5">
      <uri id="289">...</uri>
    </attachment>
    <context>
      <group id="3" name="acme-test" />
    </context>
  </comment>
  <comment id="567">...
    <context fragment="2">
      <uri id="789">...</uri>
    </context>
  </comment>
</comments>

By default, all attachments and contents are included.

Effect of attachments parameter

If attachments is none:

<comments>
  <comment id="33"
           discussionid="33"
           contentrole="Comment"
           created="2017-02-15T10:17:37+11:00">
    <title>Welcome</title>
    <author> ... </author>
    <content type="text/plain"> ... </content>
  </comment>
</comments>

If attachments is context, only the <context> element is included:

<comments>
  <comment id="33"
           discussionid="33"
           contentrole="Comment"
           created="2017-02-15T10:17:37+11:00">
    <title>Welcome</title>
    <author> ... </author>
    <!-- Context is included -->
    <content  type="text/plain"> ... </content>
    <context>
      <uri> ... </uri>
    </context>
  </comment>
  ...
</comments>

If attachments is all, both the attachments to the comment using the <attachment> element and the context are included:

<comments> 
  <comment id="33"
           discussionid="33"
           contentrole="Comment"
           created="2017-02-15T10:17:37+11:00">
    <title>Welcome</title>
    <author> ... </author>
    <content  type="text/plain"> ... </content>
    <!-- File attachments -->
    <attachment> 
      <uri> ... </uri>
    </attachment>
    <attachment>
      <uri> ... </uri>
    </attachment>
    <!-- Context of the comment -->
    <context> 
      <uri> ... </uri>
    </context>
  </comment>
  ...
</comments>

Effect of contents parameter

If contents is none, the comment content is not included:

<comments>
  <comment id="33"
           discussionid="33"
           contentrole="Comment"
           created="2017-02-15T10:17:37+11:00">
    <title>Welcome</title>
    <author> ... </author>
    <!-- Content is omitted--> 
    <attachment> 
      <uri> ... </uri> 
    </attachment> 
    <attachment> 
      <uri> ... </uri>
    </attachment>
    <context>
      <uri> ... </uri>
    </context>
  </comment>
  ...
</comments>

Effect of returngroups parameter

If returngroups is none, the comment does not include the <group> element. This is the default behavior when a comment is posted on a single group.

<comments>
  <comment id="33"
           discussionid="33"
           contentrole="Comment"
           created="2017-02-15T10:17:37+11:00">
    <title>Welcome</title>
    <author> ... </author>
    <content> ... </content>
    <context>
      <uri> ... </uri>
    </context>
    <!-- Group is omitted -->
  </comment>
  ...
</comments>

If returngroups is specified, the comment include the groups that the comment was posted on. This is the default behavior when a comment belongs to multiple groups:

<comments>
  <comment id="33"
           discussionid="33"
           contentrole="Comment"
           created="2017-02-15T10:17:37+11:00" >
    <title>Welcome</title>
    <author> ... </author>
    <content> ... </content>
    <context>
      <uri> ... </uri>
    </context>
    <!-- Group is included -->
    <group id="123" name="acme-tomato"/>
  </comment>
  ...
</comments>

Error Handling

CodeCause / Description
0x1306The Group is invalid or not accessible
0x1312The createdafter or createdbefore date is invalid
0x1313The author is invalid
Created on , last edited on