BibSonomy :: help :: BibSonomy - API URL Schema

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>