BibSonomy provides a webservice using Representational State Transfer (REST), a software architectural style for distributed hypermedia systems. The term originated in a 2000 doctoral dissertation about the web written by Roy Fielding, one of the principal authors of the HTTP protocol specification. This site is intended for developers who want to develop applications which interact with BibSonomy.
You can use the provided client library, written in Java, to access the API or you can directly interact with the webservice if you would like to write a client in a language other than Java. Furthermore, we have developed a JabRef Plugin:
For the uniform addressing and identification a URL pattern was specified. The individual inquiries can be partly supplemented with attributes of the form key=value .
An overview of the currently available methods is outlined in the following table.
|List of all users||GET||/users|
|Create a user||POST||/users|
|Details for a user||GET||/users/[username]|
|Change user details||PUT||/users/[username]|
|List of posts for a users||GET||/users/[username]/posts ?tags=[t1+t2+...+tn] ?resourcetype=(bibtex|bookmark)|
|Details for a post||GET||/users/[username]/posts/[resourceHash]|
|List of concepts for a user||GET||/users/[username]/concepts ?status=(all|picked)|
|Details for a concept for a user||GET||/users/[username]/concepts/[conceptname]|
|List of friends for a user||GET||/users/[username]/friends ?relation=(incoming|outgoing)|
|Add users as friends||POST||/users/[username]/friends|
|List of all groups||GET||/groups|
|Create a group||POST||/groups|
|Details for a group||GET||/groups/[groupname]|
|List of users for a group||GET||/groups/[groupname]/users|
|Add user to a group||POST||/groups/[groupname]/users|
|Remove user from a group||DELETE||/groups/[groupname]/users/[username]|
|Global - Tags|
|List of all tags||GET||/tags ?filter=[regex] ?(user|group|viewable)=[username/groupname] ?order=(frequency|alph)|
|Details for a tag; details for a list of sub-/super-/correlated-tags||GET||/tags/[tag]|
|Substitute the shared appearance of t1,t2,... with T1,T2,...||PUT||/substitutetags ?from=[t1+t2+..]&to=[T1+T2+..]|
|Global - Concepts|
|List of popular concepts||GET||/concepts|
|Details for a concept||GET||/concepts/[conceptname]|
|Global - Posts|
|List of all posts||GET||/posts ?tags=[t1+t2+...+tn] ?resourcetype=(bibtex|bookmark) ?(user|group|viewable)=[username/groupname] ?resource=[hash] ?search=[search_string]|
|List of recent posts||GET||/posts/added ?resourcetype=(bibtex|bookmark)|
|List of popular posts||GET||/posts/popular ?resourcetype=(bibtex|bookmark)|
All URLs can be supplemented by these attributes (use start and end only with lists):
- ?format=(xml|rdf|owl) *)
- ?start=[int], starting at 0, default 0 **)
- ?end=[int], starting at 0, default 20 **)
Tags can be customized the following way:
- ->[tag] tag and its direct children
- -->[tag] tag and its children (transitive)
- [tag]-> tag and its direct parents
- [tag]--> tag and its parents (transitive)
- <->[tag] tag and its correlated tags
Fulltext search on publications or bookmarks can be done via /posts?search=[search_string]&resourcetype=(bibtex|bookmark), see above. The search covers all available metadata for a post (e.g. title, authors, ISBN, DOI, ...) as well as associated tags. The standard behaviour when you supply more than one search term (separated by + or spaces) is that matches will be returned which contain both terms, i.e. /posts?resourcetype=bibtex&search=folksonomy+folksonomies will return publications which contain both folksonomy and folksonomies in any metadata field. Apart from this, you can enhance your search in the following ways:
- exclude terms:/posts/?search=folksonomy -ontology will return matches that contain folksonomy, but not ontology
- phrase search/posts/?search="folksonomies are cool" will return matches that contain the whole phrase "folksonomies are cool", but not matches that contain e.g. "folksonomies are not cool".
- wildcards:/posts/?search=folksonom* will return matches that contain "folksonomy, folksonomies, ...".
*) Please note: RDF and OWL are not supported at the moment.
**) ?start=0&end=20 is a list of the first 20 entities (exclusively the 'end'-value).
In case of an error the API sends the appropriate HTTP status code (please see the details of each request) and a XML document including a description of the error that occurred. In addition to that, the XML root element contains an attribute stat, whose value will be "fail" in case of an error, and "ok" otherwise.
<bibsonomy stat="fail"> <error>some error message</error> </bibsonomy>