How To
Documentation
    Learn More

      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 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

      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