How To
Documentation
    Learn More

      Web Services for Bookmarks

      This article describes the Appkit web service for bookmarks.

      Searching for bookmarks

      Bookmarks are used to identify documents for later retrieval or reference. Each bookmark is given a title, which serves to describe the intended reference. Like all other annotations, a bookmark can be optionally associated with a topic.

      Searching for bookmarks returns a collection of bookmarks that match one or more filter predicates. Supports filtering by target, by user, by topic, or by any combination of the three.

      When a large number of bookmarks 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/bookmark/{id}: Retrieves a single bookmark, identified by the id parameter.

      • POST /twigkit/api/social/bookmark: Creates a new bookmark for the authenticated user.

      • DELETE /twigkit/api/social/bookmark/{id}: Deletes permanently the bookmark identified by the id parameter.

      • GET /twigkit/api/social/bookmarks: Returns a collection of bookmarks matching some number of filter predicates.

      Parameters

      At least one predicate parameter (target, userId, or topicId) must be specified.

      target
      Optional
      Returns all bookmarks that apply to the specified target document.
      Example values: document123 or /story.news.yahoo.com/news?tmpl=story2

      userId
      Optional
      Returns bookmarks that have been created by the user with the specified numerical ID.
      Example value: 123

      topicId
      Optional
      Returns bookmarks that are in the context of the topic with the specified numerical ID.
      Example value: 456

      Example request

      Find all bookmarks that were created by user 1:

      As XML

      GET /twigkit/api/social/bookmarks?userId=1 HTTP/1.1
      Accept: application/xml
      <bookmarks>
          <bookmark 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>
              <description>
                  Reuters - Private investment firm Carlyle Group has quietly placed its bets on another part of the market.
              </description>
              <title>Carlyle Looks Toward Commercial Aerospace (Reuters)</title>
          </bookmark>
          <bookmark id="5">
              <created>2013-02-06T15:48:01.221Z</created>
              <creator id="1">
                  <full-name>admin</full-name>
                  <user-name>admin</user-name>
              </creator>
              <target>/news?u=/nm/20040814/bs_nm/markets_bears_dc</target>
              <description>
                  Reuters - Short-sellers, Wall Street's dwindling band of ultra-cynics, are seeing green again.
              </description>
              <title>My bookmark</title>
          </bookmark>
      </bookmarks>

      As JSON

      The same request, now calling for a response in JSON format:

      GET /twigkit/api/social/bookmarks?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",
              "title":"Carlyle Looks Toward Commercial Aerospace (Reuters)",
              "description":"Reuters - Private investment firm Carlyle Group has quietly placed its bets on another part of the market."
          },
          {
              "id":5,
              "created":1360165681221,
              "creator":{"id":1,"full-name":"admin","user-name":"admin"},
              "target":"/news?u=/nm/20040814/bs_nm/markets_bears_dc",
              "title":"My bookmark",
              "description":"Reuters - Short-sellers, Wall Street's dwindling band of ultra-cynics, are seeing green again."
          }
      ]

      Data operations for bookmarks

      Basic operations for handling single bookmarks: create, retrieve, and delete.

      Resource URI

      /twigkit/api/social/bookmark

      GET bookmark/{id}

      Returns a single bookmark, specified by the id path parameter.

      Parameters

      id
      Required
      A numerical value that uniquely identifies a bookmark, given as a path parameter, not a query parameter.
      Example value: 123

      Example request

      Retrieve bookmark with ID 6:

      As XML

      GET /twigkit/api/social/bookmark/6 HTTP/1.1
      Accept: application/xml
      <bookmark 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>
          <description>
              Reuters - Private investment firm Carlyle Group has quietly placed its bets on another part of the market.
          </description>
          <title>Carlyle Looks Toward Commercial Aerospace (Reuters)</title>
      </bookmark>

      As JSON

      The same request, now calling for a response in JSON format:

      GET /twigkit/api/social/bookmark/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",
          "title":"Carlyle Looks Toward Commercial Aerospace (Reuters)",
          "description":"Reuters - Private investment firm Carlyle Group has quietly placed its bets on another part of the market."
      }

      POST bookmark

      Creates a new bookmark for the authenticated user.

      Parameters

      target
      Required
      A unique identifier for a document that is bookmarked.
      Example value: document123
      Maximum length: 2083 characters

      title
      Required
      A title for the new bookmark.
      Example value: Interesting document
      Maximum length: 4000 characters

      description
      Optional
      A description of the bookmark, or the document it relates to.
      Example value: This document could be useful later.
      Maximum length: 4000 characters

      topic
      Optional
      Numerical ID of a topic which the new bookmark should relate to.
      Example value: 123

      Example request

      POST details of a new bookmark:

      POST /twigkit/api/social/bookmark/6 HTTP/1.1
      Content-Type: application/x-www-form-urlencoded
      ...
      title=Follow-up&amp;description=Look%20further%20into%20this&amp;target=document99
      <bookmark 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>
          <description>Look further into this</description>
          <title>Follow-up</title>
      </bookmark>

      DELETE bookmark/{id}

      Permanently delete the bookmark specified by the id path parameter. The operation fails if the authenticated user is not the user that created the bookmark.

      Parameters

      id
      Required
      A numerical value which uniquely identifies a bookmark. Given as a path parameter, not a query parameter.
      Example value: 123

      Example request

      Delete bookmark with ID 6:

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