Hinweis: Ein Codebeispiel für den Zugriff auf PUMA via OAuth können Sie hier herunterladen.
Die API von PUMA erlaubt Ihnen systematisch Zugriff auf Ihre Einträge. Die Hilfeseite der API beschreibt, wie Sie Ihre Anfragen auf Ihre Einträge mit Hilfe Ihres API-Keys und Ihres API-Secrets autorisieren können. Wenn Sie von Ihrer Anwendung aus für einen anderen Nutzer auf PUMA zugreifen möchten, ist dieser Weg nicht sinnvoll, da der Nutzer seinen API-Key und sein API-Secret in Ihrer Anwendung speichern müsste.
OAuth ist ein etabliertes Protokoll für sichere API-Autorisierung, die es Nutzern ermöglicht, einer dritten Anwendung den Zugriff auf ihre Daten zu erlauben, ohne, dass sie ihre Anmeldeinformationen außerhalb von PUMA angeben müssen.
Auf dieser Seite erfahren Sie, wie Sie mithilfe von OAuth von Ihrer Anwendung auf PUMA zugreifen können und OAuth Anfragen an die API von PUMA machen.
Bevor Ihre Anwendung auf die API von PUMA zugreifen kann, müssen beide Anwendungen einen gesicherten Kommunikationskanal aufbauen. Dies wird durch den Austausch von Anmeldedaten, dem sogenannten consumer key und dem consumer secret, erreicht. Der consumer key identifiziert Ihre Anwendung, und durch den consumer secret werden Ihre Anfragen verifiziert. Sowohl symmetrische (HMAC) als auch Public Key (RSA)-Verschlüsselung wird unterstützt.
Um einen consumer key und ein consumer secret zu beantragen, schreiben Sie bitte eine E-Mail an <api-support@bibsonomy.org> mit folgenden Informationen:
Hinweis: Um eine sichere Kommunikation per E-Mail zu garantieren, wird dringend empfohlen, einen Verschlüsselungsstandard (wie beispielsweise PGP) zu verwenden, um die Daten vor unberechtigtem Zugriff zu schützen und die Identität des Absenders verifizieren zu können.
Wenn ein Nutzer Ihrer Anwendung in PUMA Zugriff auf seine Daten gewährt, wird der Nutzer zwischen Ihrer Anwendung und PUMA hin- und wieder zurückgelenkt, bis am Ende der sogenannte access token Ihre Anwendung erreicht. Dieser wird dann dazu genutzt, um Ihre Anfragen an die API zu autorisieren. Dieser Prozess wird in der OAuth-Anleitung genauer beschrieben.
Im Wesentlichen muss Ihre Anwendung den Nutzer zu der PUMA-OAuth-Autorisierungsseite weiterleiten, mit den vorher erhaltenen Anmeldedaten als Request-Parameter (z.B. https://puma.scadsai.uni-leipzig.de/oauth/authorize?oauth_token=xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx):
Wenn der Nutzer Ihre temporären Anmeldedaten autorisiert, wird er entweder zu Ihrer Seite weitergeleitet (falls Sie eine Callback-URL angegeben haben), oder der Nutzer muss manuell zu Ihrer Seite wechseln. Die autorisierten Anmeldedaten können dann dazu genutzt werden, um den access token zu erhalten, mit dem Anfragen autorisiert werden.
Die OAuth-Rest-API von PUMA für Java erleichtert diesen Prozess. Falls Sie Maven nutzen, fügen Sie einfach Ihrer pom.xml-Datei den folgenden Code hinzu:
(Hinweis: PUMA basiert auf dem BibSonomy System, deshalb können die Libraries für BibSonomy auch für PUMA verwendet werden.)
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.bibsonomy</groupId>
<artifactId>oauth-rest-demo</artifactId>
<version>1.0-SNAPSHOT</version>
<repositories>
<repository>
<id>bibsonomy-repo</id>
<name>Releases von BibSonomy-Modulen</name>
<url>http://dev.bibsonomy.org/maven2/</url>
</repository>
</repositories>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0</version>
<configuration>
<source>1.7</source>
<target>1.7</target>
<compilerArguments>
<encoding>UTF-8</encoding>
</compilerArguments>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>org.bibsonomy</groupId>
<artifactId>bibsonomy-rest-client-oauth</artifactId>
<version>3.5.0</version>
</dependency>
</dependencies>
</project>
Alternativ können Sie die jar-Dateien auch direkt herunterladen.
Temporäre Anmeldedaten zu erhalten funktioniert dann folgendermaßen:
BibSonomyOAuthAccesssor accessor = new BibSonomyOAuthAccesssor("<YOUR CONSUMER KEY>", "<YOUR CONSUMER SECRET>", "<YOUR CALLBACK URL>");
String redirectURL = accessor.getAuthorizationUrl();
Nun müssen Sie den Nutzer zu redirectURL weiterleiten. Danach werden die vorher erhaltenen temporären Anmeldedaten zu einem access token umgeformt:
accessor.obtainAccessToken();
Nachdem der Autorisierungsprozess abgeschlossen ist, können Sie OAuth Anfragen an die API von PUMA machen. Erfahren Sie mehr darüber hier.