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
|
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 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
Example request
Delete bookmark with ID 6:
DELETE /twigkit/api/social/bookmark/6 HTTP/1.1