BibSonomy's
API allows you to access all of your posts programmatically. The
API's help page describes how you can authorize your requests using your API key and secret. If you want to access BibSonomy within your application in behalf of a user, this approach is not feasible, as users had to store their API key and secret within your application.
OAuth is an established protocol for secure API authorization which allows users to grant third party applications access to their data without being obliged to enter credentials outside of BibSonomy.
How to access BibSonomy from you application using OAuth
1) Request an OAuth Consumer Key and Consumer Secret
Before your application can access BibSonomy's API, both applications must establish a secured communication channel. This is done by initially exchanging credentials, a so called consumer key which identifies your application and a corresponding consumer secret which is used for signing and verifying your requests. Both symmetric (HMAC) and public key (RSA) encryption is supported.
If you want to obtain a consumer key and consumer secret for your application, please write an email to api-support@bibsonomy.org
2) Implement OAuth's authorization dance
If a user grants your application access to his data in BibSonomy, the user is redirected back and forth between your application and BibSonomy for eventually passing a so called access token to your application which can than be used to authorize your requests to the API. This process is explained in detail in the OAuth user guide.
Esentially your application needs to redirect the user to BibSonomy's OAuth authorization page with a previously obtained temporarily credentials given as request parameters (e.g. http://www.bibsonomy.org/oauth/authorize?oauth_token=xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx):
If the user authorizes your temporary credentials, you he will be either be redirected to your side (if you provided a call back url) or the user as to manually switch to your application. This authorized credential can then be used to obtain the access token which authorizes requests.
BibSonomy's OAuth Rest-API client for Java facilitates this process. If you use maven, just add the following to your pom.xml:
<project>
<repositories>
<repository>
<id>bibsonomy-repo</id>
<name>Releases von BibSonomy-Modulen</name>
<url>http://dev.bibsonomy.org/maven2/</url>
</repository>
[...]
<dependencies>
<dependency>
<groupId>org.bibsonomy</groupId>
<artifactId>bibsonomy-rest-client-oauth</artifactId>
<version>2.0.22-SNAPSHOT</version>
</dependency>
</dependencies>
[...]
Alternatively you can download the jar files
directly. Obtaining a temporarily credential is as easy as:
BibSonomyOAuthAccesssor accessor = new BibSonomyOAuthAccesssor(
"YOUR CONSUMER KEY",
"YOUR CONSUMER SECRET",
"YOUR CALLBACK URL"
);
String redirectURL = accessor.getAuthorizationUrl();
You now have to redirect the user to
redirectURL. Afterwards, the previously obtained temporarily credential is transformed to an access token:
accessor.obtainAccessToken();
3) Make requests to BibSonomy's API
You can now use BibSonomy's rest logic interface to perform API operations.
RestLogicFactory rlf = new RestLogicFactory(
"http://www.bibsonomy.org/api",
RenderingFormat.XML
);
LogicInterface rl = rlf.getLogicAccess(accessor);
[...]
rl.createPosts(uploadPosts);
[...]
A running example can be found on
the corresponding help page in BibSonomy.
If you have further questions, please feel free to write a mail to
api-support@bibsonomy.org.
