Wiki

Clone wiki

BibSonomy / documentation / api / REST 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, there is a customized JabRef-Client available:

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 Method 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 user GET /users/[username]/posts ?tags=[t1+t2+...+tn] ?resourcetype=(publicationǀ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] 🆗
Add document of a post POST /users/[username]/posts/[resourcehash]/documents/ 🆗
Document of a post GET /users/[username]/posts/[resourcehash]/documents/[fileName] 🆗
Rename document of a post PUT /users/[username]/posts/[resourcehash]/documents/[fileName] 🆗
Delete document of a post DELETE /users/[username]/posts/[resourcehash]/documents/[fileName] 🆗
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] 🆗
Posts in clipboard GET /users/[username]/clipboard 🆗
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] ❌
Persons
List of all persons GET /persons ❌
Create a new person POST /persons ❌
Details for a person GET /persons/[personid] ❌
Update details for a person PUT /persons/[personid] ❌
List of posts for a person GET /persons/[personid]/posts ❌
List of relations for a person GET /persons/[personid]/relations ❌
Add relation to a person POST /persons/[personid]/relations ❌
Merge for a person POST /persons/[personid]/merge ❌
Delete relation of a person by interhash, type and index DELETE /persons/[personid]/relations/[interhash]/[type]/[index] ❌
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] 🆗
Correlated tags for specific tag(s) GET /tags/[tag1+tag2+...] ?relation=(relatedǀsimilar) ?(userǀgroupǀviewable)=([username]ǀ[groupname]) ?order=(frequencyǀalph) 🆗
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=(publicationǀbookmark) ?(userǀgroupǀviewable|person)=[username/groupname/personid] ?resource=[hash] ?search=[search_string] 🆗
List of recent posts GET /posts/added ?resourcetype=(publicationǀbookmark) 🆗
List of popular posts GET /posts/popular ?resourcetype=(publicationǀbookmark) 🆗

##Format-Parameters All URLs can be supplemented by these attributes (use start and end only with lists):

  • ?format=(xml|json|csl|bibtex|endnote) (only xml and json are supported for input, the remaining formats only for output of publications)
  • ?start=[int], starting at 0, default 0 **)
  • ?end=[int], starting at 0, default 20 **)

E.g., ?start=0&end=20 returns a list of the first 20 entities (exclusively the 'end'-value).

Tags can be customized in 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=(publication|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=publication&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=isbn: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="isbn:978-0-387-71000-6"

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.

#!xml
<bibsonomy stat="fail">
    <error>some error message</error>
</bibsonomy>

Updated