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 relavance 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 the id parameter.
POST /twigkit/api/social/comment: Post a comment.
DELETE /twigkit/api/social/comment/{id}: Delete a single comment, identified by the id parameter.

GET comments

Get comments that satisfy one or more predicates.

Parameters

Note	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/comment

GET 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

Example request

Delete the comment with ID 6:

DELETE /twigkit/api/social/comment/6 HTTP/1.1