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

Note
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 valus: 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 which 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 being bookmarked.
Example value: document123
Maximum length: 2083 characters

title
required
A title for the new bookmark.
Example values: Interesting document
Maximum length: 4000 characters

description
optional
A description of the bookmark, or the document it relates to.
Example values: 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 values: 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 in the first place.

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