Comment
Comment Service
Web service endpoints for comments.
Examples:
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
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
Jump to
- Create Comment
- Create Comment Like
- Create Extended Properties
- Create Outcome
- Create Reply
- Destroy Comment
- Destroy Comment Like
- Destroy Extended Properties
- Get Comment
- Get Comment Likes
- Get Comments
- Get Editable Comment
- Get Extended Properties
- Get Outcomes
- Get Outcome Types
- Lock Editable Comment
- Lock Editable Comment
- Update Comment
- Update Editable Comment
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:
Name | Type | Required | Description |
---|---|---|---|
author | Boolean | false | Flag indicating if new comment is an author comment or a regular comment (only valid for documents). By default a regular comment will be created. |
fields | String | false | Fields to include in the returned Comment |
Takes:
Return Status:
HTTP Status Code | Description |
---|---|
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 Like
POST /comments/{commentID}/likes
Register that the requesting person likes the specified comment.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment to be liked |
Return Status:
HTTP Status Code | Description |
---|---|
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 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.
Return Status:
HTTP Status Code | Description |
---|---|
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 Outcome
POST /comments/{commentID}/outcomes
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which to create the outcome |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | Fields to be returned on the new outcome |
Takes:
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
400 (Bad Request) | An input field is missing or malformed |
409 (Conflict) | Ad 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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment being replied to |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | Fields to include in the returned Comment |
Takes:
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment to be deleted |
Return Status:
HTTP Status Code | Description |
---|---|
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 Like
DELETE /comments/{commentID}/likes
Delete the like of the specified content object by the requesting user.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which a like is being removed |
Return Status:
HTTP Status Code | Description |
---|---|
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 Extended Properties
DELETE /comments/{commentID}/extprops
Delete the existing extended properties for the specified comment.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which the extended properties are to be deleted |
Return Status:
HTTP Status Code | Description |
---|---|
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 |
Get Comment
GET /comments/{commentID}
Return the specified content object with the specified fields.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment to be returned |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | Fields to be returned |
abridged | Boolean | false | Flag indicating that if content.text is requested, it will be abridged
(length shortened, HTML tags removed) |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which to return liking people |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
startIndex | Integer | false | Zero-relative index of the first person to be returned |
count | Integer | false | Maximum number of people to be returned |
fields | String | false | Fields to be returned on liking people |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which to return reply comments |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
excludeReplies | Boolean | false | Flag indicating whether to exclude replies (and therefore return direct replies only) |
startIndex | Integer | false | Zero-relative index of the first comment to be returned |
count | Integer | false | Maximum number of comments to be returned |
anchor | String | false | optional 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. |
fields | String | false | Fields to be returned in the selected comments |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment to be returned |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | Fields to be returned |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which to return extended properties |
Return Status:
HTTP Status Code | Description |
---|---|
200 (OK) | Request was successful |
404 (Not Found) | Specified comment does not exist |
Get Outcomes
GET /comments/{commentID}/outcomes
Return a paginated list of the outcomes for the specified comment.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which to return outcomes |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
startIndex | Integer | false | Zero-relative index of the first outcome to be returned |
count | Integer | false | Maximum number of outcomes to be returned |
fields | String | false | Fields to be returned on outcomes |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment for which to return outcomes |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
startIndex | Integer | false | Zero-relative index of the first outcome type to be returned |
count | Integer | false | Maximum number of outcome types to be returned |
fields | String | false | Fields to be returned on outcome types |
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment to be locked |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | Fields to include in the returned entity |
Return Status:
HTTP Status Code | Description |
---|---|
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 |
Lock 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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment to be unlocked |
Return Status:
HTTP Status Code | Description |
---|---|
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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the comment to be updated |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | Fields to include in the returned entity |
Takes:
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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:
Name | Type | Required | Description |
---|---|---|---|
commentID | String | true | ID of the editable comment to be updated |
Query Parameters:
Name | Type | Required | Description |
---|---|---|---|
fields | String | false | Fields to include in the returned entity |
Takes:
Retrieves:
Return Status:
HTTP Status Code | Description |
---|---|
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 |