Web service API

How to use PageSeeder's Web service API

find comments public

/comments/find [GET]

com.pageseeder.comment.GetCommentsByFilter

Description

This service returns a list of public comments using parameters to filter the results, the list of groups specified must be public groups.

Note

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
groupsA comma-separated list of group names the comments must belong toyesstrings
archivedif "true" include archived commentsnobooleanfalse
attachmentsThe attachments to include
(can be "none", "context" or "all")
noenumall
authorThe member id of the comments authornolong
contentsThe contents to include
(can be "none" or "all")
noenumall
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 labelsnostring
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 search first comment in a discussion (may be faster when using paths)nostringany
returngroupsThe groups to return in the output (can be "none","specified")noenum"none" or if multiple groups "specified"
statusescomma-separated list of statusesnostatus
titleThe title the comments must have (optional wild card * suffix, use ** to escape)nostring
typeThe type the comments must have (optional wild card * suffix, use ** to escape)nostring

Including all attachments, contents and returned groups can incur a performance penalty when loading large discussions. Smce of the parameters below allows developers to control whether they should be loaded and returned or not.

attachments

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

  • none - No attachment should be included
  • context - Only include the context document or URL
  • all - Include all attachments

Note

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

contents

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

Possible options are:

  • none - The content should not be loaded
  • all - Load the content of all comments

Note

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 have been created through the API.

returngroups

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

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

Possible options are:

  • none - The groups should not be loaded
  • specified - Load the content of all comments

statuses

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

Permission

If the parameter emails is set to all the the permissions are restricted to administrators only.

The other restriction is that the groups parameter can only list groups that have public access.

Response

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

<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 -->
      <context 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 inlcuded:

<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 behaviour 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 one. This is the default behaviour 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