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:

• Java client library (see also these examples)
• Python client library
• PHP client library
• direct access
• JabRef client

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>