help · blog · about
A blue social bookmark and publication sharing system.

API

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:

Methods

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.

Description HTTP Path Status
Users
List of all users GET /users
Create a user POST /users
Details for a user GET /users/[username]
Change user details PUT /users/[username]
Delete user DELETE /users/[username]
List of posts for a users GET /users/[username]/posts ?tags=[t1+t2+...+tn] ?resourcetype=(bibtex|bookmark)
Create post POST /users/[username]/posts
Details for a post GET /users/[username]/posts/[resourceHash]
Change post PUT /users/[username]/posts/[resourceHash]
Delete post DELETE /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]
Create concept POST /users/[username]/concepts/[conceptname]
Update concept PUT /users/[username]/concepts/[conceptname]
Delete concept DELETE /users/[username]/concepts/[conceptname]
Friends
List of friends for a user GET /users/[username]/friends ?relation=(incoming|outgoing)
Add users as friends POST /users/[username]/friends
Groups
List of all groups GET /groups
Create a group POST /groups
Details for a group GET /groups/[groupname]
Change group PUT /groups/[groupname]
Delete group DELETE /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, ...".
Special characters in search terms: Please note that all special (i.e. non-alphanumeric) characters occuring in search terms apart from "_" and "'" are treated as search term separators - if you search e.g. for an ISBN like /posts?search=978-0-387-71000-6 , then you also an entry with ISBN 387-0-978-71000-6 will be matched, because the number blocks are treated as distinct search terms, which is not what you want. In such a case, phrase search will yield the expected result:
  • /posts?search="978-0-387-71000-6"

*) 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).

Errors

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>