Getting started

1. Testen der API Endpoints

Unter dem Menüpunkt „API Endpoints“ befindet sich die Dokumentation aller verfügbaren RIS-Synergy Endpoints. Es besteht hier auch die Möglichkeit, die Endpoints ohne Authentifizierung auszuprobieren. Es werden dabei Beispieldaten zu den jeweiligen Endpoints ausgeliefert.

Die Autorisierung mittels OAuth 2 kann unabhängig davon über folgende Test-Endpoints getestet werden:

OAUTH_SERVER_URL:
https://oauth2-staging.aau.at/oauth/token
INFO_ENDPOINT:
https://cris-staging.aau.at/ris-synergy/info/v1/oauth/info/
curl --request POST \
  --url 'https://AUTH_SERVER_DOMAIN/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=CLIENT_ID \
  --data client_secret=CLIENT_SECRET 
curl --request GET \
  --url https://API_ENDPOINT_DOMAIN \
  --header 'authorization: Bearer ACCESS_TOKEN' \
  --header 'content-type: application/json'

Die dazu benötigten Client Credentials stehen unter folgenden Link zu Verfügung: https://seafile.aau.at/f/b7832719ffd641e9a9c1/?dl=1
Um Zugang zu den Credentials zu erhalten bitte eine Anfrage an ris-synergy@tuwien.ac.at
Die URLs zum OAUTH-Server und zum Info-Endpoint sind für den Real-Betrieb für alle teilnehmenden Einrichtungen in der Registry hinterlegt.

Weitere Beispiele und Informationen zum Authentifizierungs-Workflow finden Sie hier.

Die Verwaltung eines Authentifizierungsservers für die Umsetzung des Client Credentials Flows (siehe API Sicherheit) ist jedem Knoten selbst überlassen. Als Hilfestellung bieten sich hier z.B. folgende Tutorials zur Erstellung einer OAuth Client Applikation und zum Anlegen eines neuen Clients mithilfe von Keycloak an:

https://www.appsdeveloperblog.com/keycloak-create-a-new-oauth-client-application/

https://www.appsdeveloperblog.com/keycloak-client-credentials-grant-example/

Zur Anbindung ans RIS Synergy Netzwerk siehe auch: Eintrag in die Registry & Austausch von Credentials

2. API und Client Code generieren

Im Folgenden wird Swagger Codegen 3.X (3.0.0 branch) zur Generierung des API und Client Codes verwendet. Details zur Installation und weitere Beispiele zur Verwendung sind auch auf dem offiziellen Github Repository zu finden.

In der Dokumentation zu den RIS Synergy Endpoints befindet sich jeweils ein Link zum API Specification File, welches zum Generieren des Codes benötigt wird. Wichtig: In der aktuellen Version von Swagger Codegen kommt es bei manchen Frameworks noch zu Problemen beim Generieren des Codes aus dem Specification File (zum Github Issue). Man kann dieses Problem aber einfach umgehen, in dem zum Generieren zusätzlich noch folgendes Template File verwendet wird: Download(zip).

Genieren von Client Code via CLI (URL)

git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen

java -jar  modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate\
  -i https://cris-staging.aau.at/ris-synergy/funding/v3/api-docs\
  -l java \
  -t <template directory> \
  -o samples/client/ris-synergy/java

cd samples/client/ris-synergy/java
mvn package

Generieren von Client Code via CLI (lokale Datei)

Alternativ kann das Specification File lokal im json Format abgespeichert und für das Generieren des Client Codes verwendet werden.

git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i ./path/to/local/file/spec.json \
  -l java \
  -t <template directory> \
  -o samples/client/ris-synergy/java

Weitere Details und Optionen zum Generieren vom Client Code sind auch auf https://github.com/swagger-api/swagger-codegen#getting-started zu finden.

Generieren von Server-Stub Code

Das Generieren von Server-Stub Code unterscheidet sich je nach Framework. Beispiele zu den verschieden Frameworks sind auf https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO gegeben. Das Specification File kann genau wie beim Generieren des Client Codes über eine URL abgefragt oder lokal hinterlegt werden.

Java Spring Boot
git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i https://cris-staging.aau.at/ris-synergy/funding/v3/api-docs \
  -l spring \
  -t <template directory> \
  -o samples/server/ris-synergy/springboot

Generieren von Client/Server Stub Code mit Maven

Das Generieren des Codes kann auch mithilfe des Swagger Codegen Maven Plugins verwaltet werden. Dazu werden folgende Ergänzungen in der pom.xml File benötigt: 

<dependency>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.34</version>
</dependency>
<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.3.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>path/to/file/spec.json</inputSpec>
                <templateDirectory>path/to/template directory</templateDirectory>
                <language>java</language>
                <configOptions>
                   <sourceFolder>src/gen/java/main</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Ausführliche Details und Beispiele zur Verwendung des Swagger Codegen Maven Plugins sind auf https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen-maven-plugin/README.md beschrieben.