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 theidparameter. -
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 theidparameter. -
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&description=Look%20further%20into%20this&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