Comment

Comment Service

Web service endpoints for comments.

Examples:
Create Comment

POST to /comments with the parent field containing the URI of a content object or another comment. Suppose you have a blog post with URI "http://example.jiveon.com/api/core/v3/contents/1234". Then the following curl command will comment on this post.

curl -u joe.employee:password -H "Content-Type: application/json" --data '{ "type": "comment", "content": { "type": "text/html", "text":"<p>Your ideas for our budget are great!</p>"}, "subject": "Insightful blog post", "parent": "http://example.jiveon.com/api/core/v3/contents/1234"}' http://example.jiveon.com/api/core/v3/comments

Like a Comment

In order to like a comment, you must POST to /comments/{commentID}/likes with an empty request body. Note that a user cannot like her own comments, so you must like a comment with different credentials. Curl example:

curl -u another.user:password -X POST http://example.jiveon.com/api/core/v3/comments/1234/likes

Create Abuse Report

POST /comments/{commentID}/abuseReports

Register that the requesting person considers the specified comment as abusive. See AbuseReport for an example.

Path Parameters:
NameTypeRequiredDescription
commentIDStringtrueID of the comment to be marked as abusive
Takes:
  • AbuseReport containing the abuse report information
    • Retrieves:
  • AbuseReport containing the newly created abuse report
    • Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access or mark this content as abusive
    404 (Not Found)The specified content does not exist

    Create Comment

    POST /comments

    Create a new comment with the specified characteristics. The parent field must contain the URI of either a content object for which this is a direct reply, or the URI of a previous comment to which this is a reply.

    Query Parameters:
    NameTypeRequiredDescription
    authorBooleanfalseFlag indicating if new comment is an author comment or a regular comment (only valid for documents). By default a regular comment will be created.
    publishedStringfalseDate and time when this content object was originally created. Set 'updated' param as well. Only set this field when importing content. Since 3.6.
    updatedStringfalseDate and time when this content object was most recently updated. Set 'published' param as well. Only set this field when importing content. Since 3.6.
    fieldsStringfalseFields to include in the returned Comment
    Takes:
  • Comment describing the comment to be created
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)You attempt to add a comment to a content object that does not support them, or for which comments have been closed
    403 (Forbidden)You are not allowed to perform this operation
    404 (Not Found)The specified parent content object (or comment) cannot be found

    Create Comment Helpful

    POST /comments/{commentID}/helpful

    Register that the requesting person considers the specified comment helpful.

    Note: If this is the first time the specified content has been marked helpful a helpful outcome will be created

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be marked as helpful
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access or mark this comment as helpful
    404 (Not Found)The specified comment does not exist

    Create Comment Like

    POST /comments/{commentID}/likes

    Register that the requesting person likes the specified comment.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be liked
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access or like this comment
    404 (Not Found)The specified comment does not exist

    Create Comment Unhelpful

    POST /comments/{commentID}/unhelpful

    Register that the requesting person considers the specified comment unhelpful.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be marked as unhelpful
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this comment or mark this comment as unhelpful
    404 (Not Found)The specified comment does not exist

    Create Extended Properties

    POST /comments/{commentID}/extprops

    Save a new set of extended properties for a comment, and return an entity representing the newly created extended properties. Any previous extended properties for this comment will be completely replaced.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being stored on the target comment will be also associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which the extended properties are to be created
    Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for this comment
    404 (Not Found)The specified comment does not exist

    Create Extended Properties For Addon

    POST /comments/{commentID}/extprops/addOn/{addonUUID}

    Save a new set of extended properties for a comment, and return an entity representing the newly created extended properties. Any previous extended properties for this comment will be completely replaced.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which the extended properties are to be created
    addonUUIDStringtrueUUID of the addon for which the properties are created.
    Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for this comment
    404 (Not Found)The specified comment does not exist
    Since: 3.9

    Create Outcome

    POST /comments/{commentID}/outcomes
    Create the outcome on the specified comment
    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which to create the outcome
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned on the new outcome
    Takes:
  • the outcome to create
    • Retrieves:
  • Outcome describing the new create outcome on that comment
    • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)An outcome of this type already exists on the comment
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Create Reply

    POST /comments/{commentID}/comments

    Create a new comment as a reply to an existing comment with the specified characteristics.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment being replied to
    Query Parameters:
    NameTypeRequiredDescription
    publishedStringfalseDate and time when this content object was originally created. Set 'updated' param as well. Only set this field when importing content. Since 3.6.
    updatedStringfalseDate and time when this content object was most recently updated. Set 'published' param as well. Only set this field when importing content. Since 3.6.
    fieldsStringfalseFields to include in the returned Comment
    Takes:
  • Comment describing the reply comment to be created
    • Retrieves:
  • Comment describing the new reply comment
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)You attempted to add a comment to a content object that does not support them, or for which comments have been closed
    403 (Forbidden)You are not allowed to perform this operation
    404 (Not Found)The specified parent content object (or comment) cannot be found

    Destroy Comment

    DELETE /comments/{commentID}

    Delete the specified comment and sub comments recursively.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be deleted.
    Query Parameters:
    NameTypeRequiredDescription
    recursiveDeleteBooleanfalseFlag indicating if the delete is recursive. The flag defaults to true if not provided.
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the specified comment
    404 (Not Found)The specified comment does not exist

    Destroy Comment Helpful

    DELETE /comments/{commentID}/helpful

    Delete the helpful mark of the specified comment by the requesting user.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which a like is being removed
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)Any input field is malformed
    409 (Conflict)You do not currently have a helpful mark registered for this comment
    403 (Forbidden)You are not allowed to access or remove the helpful mark for this comment
    404 (Not Found)The specified comment does not exist

    Destroy Comment Like

    DELETE /comments/{commentID}/likes

    Delete the like of the specified content object by the requesting user.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which a like is being removed
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)Any input field is malformed
    409 (Conflict)You do not currently have a like registered for this comment
    403 (Forbidden)You are not allowed to access or unlike this comment
    404 (Not Found)The specified comment does not exist

    Destroy Comment Unhelpful

    DELETE /comments/{commentID}/unhelpful

    Delete the registration of the specified comment as unhelpful by the requesting user.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which an unhelpful registration is being removed
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)You do not currently have an unhelpful mark registered for this comment
    403 (Forbidden)You are not allowed to access this comment or remove the registration of this comment as unhelpful
    404 (Not Found)The specified comment does not exist

    Destroy Extended Properties

    DELETE /comments/{commentID}/extprops

    Delete the existing extended properties for the specified comment.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being deleted on the target place will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which the extended properties are to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete extended properties
    404 (Not Found)The specified comment does not exist

    Destroy Extended Properties For Addon

    DELETE /comments/{commentID}/extprops/addOn/{addonUUID}

    Delete the existing extended properties for the specified comment.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which the extended properties are to be deleted
    addonUUIDStringtrueUUID of the addon for which the properties are deleted.
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete extended properties
    404 (Not Found)The specified comment does not exist
    Since: 3.9

    Get Abuse Reports

    GET /comments/{commentID}/abuseReports

    Retrieve the abuse reports for the specified comment

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment marked as abusive
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned in the abuse report response
    Retrieves:
  • AbuseReport[] containing the abuse reports for the specified content
    • Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access or mark this content as abusive
    404 (Not Found)The specified content does not exist

    Get Comment

    GET /comments/{commentID}

    Return the specified content object with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Comment containing the specified comment
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the specified comment
    404 (Not Found)The specified comment does not exist

    Get Comment Likes

    GET /comments/{commentID}/likes

    Return a paginated list of the people who like the specified comment.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which to return liking people
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first person to be returned
    countIntegerfalseMaximum number of people to be returned
    fieldsStringfalseFields to be returned on liking people
    Retrieves:
  • Person[] listing the people who like the specified comment
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Get Comments

    GET /comments/{commentID}/comments

    Return a paginated list of comments to the specified content object, optionally limiting the returned results to direct replies only. The specified content object type must support comments, or be a comment itself (in which case replies to this comment only are returned).

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which to return reply comments
    Query Parameters:
    NameTypeRequiredDescription
    excludeRepliesBooleanfalseFlag indicating whether to exclude replies (and therefore return direct replies only)
    startIndexIntegerfalseZero-relative index of the first comment to be returned
    countIntegerfalseMaximum number of comments to be returned
    anchorStringfalseoptional URI for a comment to anchor at. Specifying a anchor will try to return the page containing the anchor. If the anchor could not be found then the first page of comments will be returned.
    fieldsStringfalseFields to be returned in the selected comments
    Retrieves:
  • Comment[]
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the specified comment or its replies
    404 (Not Found)The specified comment does not exist

    Get Editable Comment

    GET /comments/{commentID}/editable

    Return the specified editable content object with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned
    Retrieves:
  • Comment containing the specified editable comment
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)if content is already being edited by another user
    403 (Forbidden)You are not allowed to access the specified comment
    404 (Not Found)The specified comment does not exist

    Get Extended Properties

    GET /comments/{commentID}/extprops

    Return the extended properties for the specified comment.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being fetched from the target place will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which to return extended properties
    Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    404 (Not Found)Specified comment does not exist

    Get Extended Properties For Addon

    GET /comments/{commentID}/extprops/addOn/{addonUUID}

    Return the extended properties for the specified comment.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which to return extended properties
    addonUUIDStringtrueUUID of the addon for which the properties are fetched.
    Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    404 (Not Found)Specified comment does not exist
    Since: 3.9

    Get Have Marked Helpful

    GET /comments/{commentID}/helpful

    Return a paginated list of the people who consider this comment helpful.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment that has been marked helpful
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first person to be returned (default is 0)
    countIntegerfalseMaximum number of people to be returned (default is 25)
    fieldsStringfalseFields to be returned on people who have marked this comment as helpful (default is @summary)
    Retrieves:
  • Person[] listing people who also have marked this comment helpful
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Get Have Marked Unhelpful

    GET /comments/{commentID}/unhelpful

    Return a paginated list of the people who consider this comment unhelpful.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment that has been marked unhelpful
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first person to be returned (default is 0)
    countIntegerfalseMaximum number of people to be returned (default is 25)
    fieldsStringfalseFields to be returned on people who have marked this comment as unhelpful (default is @summary)
    Retrieves:
  • Person[] listing people who also have marked this comment unhelpful
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Get Outcomes

    GET /comments/{commentID}/outcomes

    Return a paginated list of the outcomes for the specified comment.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which to return outcomes
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first outcome to be returned
    countIntegerfalseMaximum number of outcomes to be returned
    fieldsStringfalseFields to be returned on outcomes
    Retrieves:
  • Outcome[] listing the outcomes who like the specified comment
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Get Outcome Types

    GET /comments/{commentID}/outcomeTypes

    Return a paginated list of the possible outcome types for the specified comment.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment for which to return outcomes
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first outcome type to be returned
    countIntegerfalseMaximum number of outcome types to be returned
    fieldsStringfalseFields to be returned on outcome types
    Retrieves:
  • OutcomeType[] listing the outcome types who like the specified comment
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Lock Editable Comment

    POST /comments/{commentID}/editable

    Attempt to lock the specified comment for editing. This method will not fail if the comment is already locked. Check the 'editingBy' field in returned entity to see who owns the lock.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be locked
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned entity
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field was malformed
    409 (Conflict)if content is already being edited by another user
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Unlock Editable Comment

    DELETE /comments/{commentID}/editable

    Attempt to unlock the specified comment for editing. This method will not fail if the comment is not locked or the lock is owned by another user. Check the 'editingBy' field in returned entity to see who owns the lock.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be unlocked
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field was malformed
    403 (Forbidden)You are not allowed to access this comment
    404 (Not Found)The specified comment does not exist

    Update Comment

    PUT /comments/{commentID}

    Update the specified comment with the specified characteristics.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the comment to be updated
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned entity
    updatedStringfalseDate and time when this content object was most recently updated.
    Takes:
  • Comment containing the updated comment
    • Retrieves:
  • Comment representing the updated comment
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)You attempt to add a comment to a content object that does not support them, or for which comments have been closed
    403 (Forbidden)You are not allowed to access the specified comment
    404 (Not Found)The specified comment does not exist

    Update Editable Comment

    PUT /comments/{commentID}/editable

    Update the specified editable comment with the specified characteristics.

    Path Parameters:
    NameTypeRequiredDescription
    commentIDStringtrueID of the editable comment to be updated
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned entity
    updatedStringfalseDate and time when this content object was most recently updated.
    Takes:
  • Comment containing the updated comment
    • Retrieves:
  • Comment representing the updated comment
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)You attempt to add a comment to a content object that does not support them, or for which comments have been closed
    403 (Forbidden)You are not allowed to access the specified comment
    404 (Not Found)The specified comment does not exist