Web Services for Comments
This article describes Appkit web services for comments.
Searching for comments
Users provide additional information about documents by commenting on them. For example, users might comment on the quality or relevance of a document, expand upon information in a document, or refer to related documents.
Searching for comments returns a collection of comments that match one or more filter predicates. Searches support filtering by target, by user, by topic, or by any combination of the three.
When a large number of comments match the specified predicates, only the 10 most recent entries are returned.
Methods and resource URIs
Methods and resource URIs are:
-
GET /twigkit/api/social/comments: Retrieve comments that match one or more predicates. -
GET /twigkit/api/social/comment/{id}: Retrieve a single comment, identified by theidparameter. -
POST /twigkit/api/social/comment: Post a comment. -
DELETE /twigkit/api/social/comment/{id}: Delete a single comment, identified by theidparameter.
GET comments
Get comments that satisfy one or more predicates.
Parameters
At least one predicate parameter (target, userId, or topicId) must be specified.
|
target
Optional
Returns all comments that apply to the specified target document.
Example values: document123 or /story.news.yahoo.com/news?tmpl=story2
userId
Optional
Returns comments that have been created by the user with the specified numerical ID.
Example value: 123
topicId
Optional
Returns comments that are in the context of the topic with the specified numerical ID.
Example value: 456
Example request
Find all comments that were created by user 1:
As XML
GET /twigkit/api/social/comments?userId=1 HTTP/1.1
Accept: application/xml<comments>
<comment id="6">
<created>2013-02-06T15:48:27.047Z</created>
<creator id="1">
<full-name>admin</full-name>
<user-name>admin</user-name>
</creator>
<target>/news?u=/nm/20040814/bs_nm/column_mergers_dc</target>
<text>Very good</text>
</comment>
</comments>As JSON
The same request, now calling for a response in JSON format:
GET /twigkit/api/social/comments?userId=1 HTTP/1.1
Accept: application/jsonrequest[
{
"id":6,
"created":1360165707047,
"creator":{"id":1,"full-name":"admin","user-name":"admin"},
"target":"/news?u=/nm/20040814/bs_nm/column_mergers_dc",
"text":"Very good"
}
]Data operations for comments
Basic operations for handling single comments are: create, retrieve, and delete.
Resource URI
/twigkit/api/social/commentGET comment/{id}
Retrieve a single comment, specified by the id path parameter.
Parameters
id
Required
A numerical value that uniquely identifies a comment, given as a path parameter, not a query parameter.
Example value: 123
Example request
Retrieve comment with ID 6:
As XML
GET /twigkit/api/social/comment/6 HTTP/1.1
Accept: application/xml<comment id="6">
<created>2013-02-06T15:48:27.047Z</created>
<creator id="1">
<full-name>admin</full-name>
<user-name>admin</user-name>
</creator>
<target>/news?u=/nm/20040814/bs_nm/column_mergers_dc</target>
<text>must follow up on this</text>
</comment>As JSON
The same request, now calling for a response in JSON format:
GET /twigkit/api/social/comment/6 HTTP/1.1
Accept: application/jsonrequest{
"id":6,
"created":1360165707047,
"creator":{"id":1,"full-name":"admin","user-name":"admin"},
"target":"/news?u=/nm/20040814/bs_nm/column_mergers_dc",
"text":"must follow up on this"
}POST comment
Creates a new comment for the authenticated user.
Parameters
target
Required
A unique identifier for a document that is commented on.
Example value: document123
Maximum length: 2083 characters
text
Required
The text of the new comment.
Example value: Interesting document
Maximum length: Effectively none (that is, the length of a comment is constrained by the maximum LOB length of the underlying database)
topic
Optional
Numerical ID of a topic that the new comment relates to.
Example value: 123
Example request
Create a new comment:
POST /twigkit/api/social/comment/6 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
...
text=Follow%20up%20on%20this<comment id="7">
<created>2013-02-06T15:48:27.047Z</created>
<creator id="1">
<full-name>admin</full-name>
<user-name>admin</user-name>
</creator>
<target>document99</target>
<text>Follow up on this</description>
</bookmark>DELETE comment/{id}
Permanently delete the comment specified by the id path parameter. The operation fails if the authenticated user is not the user that created the comment in the first place.
Parameters
id
Required
A numerical value which uniquely identifies a comment, given as a path parameter, not a query parameter.
Example value: 123