|
|
# ASiST-Server Tutorial
|
|
|
|
|
|
Der OpenASiST-Server ist eine zentrale Anlaufstelle für alle App-Instanzen, welcher jede App zu einer Hochschule zuordnen kann. Die Apps kommunizieren mit Hilfe von HTTP und einer REST-Schnittelle mit dem ASiST-Server. Der Aufbau der URL ist folgendermaßen:
|
|
|
|
|
|
https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/{modul}/{university}/{action}
|
|
|
|
|
|
Es müssen immer mindestens 3 Pfad-Paramter übergeben werden, welche in diesem Beispiel mit {}-Klammern gekennzeichnet sind. Der {modul}-Parameter beschreibt, welchen Funtkionalitätsbereich des ASiST-Servers verwendet werden soll. An dieser Stelle kann zum Beispiel 'canteen' eingesetzt werden, um die Mensa-Funktionen des ASiST-Server aufzurufen. Mit Hilfe des {university}-Paramters, wird die benötigte Universität übermittelt. Jede Universität besitzt ein Kürzel, welches im Falle der TU Chemnitz die Zeichenkette 'tuc' ist.
|
|
|
Damit der ASiST-Server weiß, welche Aktion/Funktionalität ausgeführt werden soll, ist zuletzt der {action}-Paramter zu setzen. Beispielsweise kann diesem Parameter der Wert 'list' oder 'all' zugewiesen werden, wodurch der ASiST-Server eine Liste von Informationen zusammenstellt und dem Clienten zurücksendet.
|
|
|
|
|
|
Somit interpretiert der ASiST die URL
|
|
|
https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/canteen/tuc/all
|
|
|
wie folgt: Stelle eine Liste aller Mensen und Cafeterias der TU Chemnitz zusammen.
|
|
|
|
|
|
Währenddessen liefert die URL
|
|
|
https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/canteen/tuc/today
|
|
|
das Essen des derzeitigen Tages zurückliefert.
|
|
|
|
|
|
Dieser Dokumentation ist als Ergänzung zur interaktiven [API-Dokumentation](https://urz-asist.hrz.tu-chemnitz.de/asist/api-doc/app/index.html) zu verstehen.
|
|
|
|
|
|
# Module
|
|
|
Der ASiST-Server ist modular Aufgebaut, wodurch einzelne Module voneinander unabhängig aktiviert oder deaktiviert werden können. Ein Modul bündelt Funktionalität, die thematisch zusammenfassbar sind. Zum Beispiel fasst das Modul Canteen alle Funktionen zusammen, die Informationen zu dem Mensaangebot bereitstellen.
|
|
|
|
|
|
## Canteen
|
|
|
Das Cannteen-Modul stellt Informationen für alle Mensen und Caferterias einer Universität bereit.
|
|
|
### https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/canteen/tuc/{date}
|
|
|
Der {date}-Parameter ist im Format '[yyyy-MM-dd](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)'({4-stellige Jahreszahl}-{2-stelliger Monat}-{2-stelliger Tag}) zu übertragen.
|
|
|
Um nicht das derzeitige Datum ermitteln und formatieren zu müssen, reicht es den {date}-Parameter mit dem Wert 'today' zu setzen, damit das Essen des derzeitigen Tages zurückgeliefert wird.
|
|
|
|
|
|
## Feeds
|
|
|
Dieses Modul ist für die Verarbeitung und Bereitstellung von Campusneuigkeiten zuständig. Die korrekte Verwendung der Feed-API sieht folgendes Vorgehen vor:
|
|
|
Zuerst ist die Liste der Nachrichten-Kanäle vom ASiST-Server abzuholen, um ID, Titel und Beschreibung eines Kanals zu erhalten. Anschließend sind die Beiträge/Artikel für jeden Kanal einzeln abzurufen, indem die ID des entsprechenden Kanals aus der Liste der Kanäle ausgelesen wird und ein weiterer Request an den ASiST-Server gestellt wird.
|
|
|
### https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/v2/feed/tuc/list
|
|
|
Über diese URL können alle Blogs, RSS-Feeds oder Nachrichten-Kanäle einer Universität abgerufen werden. Um eine bessere Internationalisierung zu ermöglichen, wird der [Accept-Language-Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) unterstützt. Dieser wird zusätzlich zur URL im Request mitgesendet, wodurch dieser optional gesetzt werden kann. Der ASiST-Server filtert die auszugebende Liste der Nachrichten-Kanäle anhand der im Accept-Language-Header hinterlegten Sprachen, damit nur Blogs und Feeds in den gewünschten Sprachen übermittelt werden. Findet der ASiST-Server keinen Accept-Language-Header, wird der Filtermechanismus nicht angewendet und der Client bekommt eine Liste aller Narichten-Kanäle zur Verfügung gestellt.
|
|
|
|
|
|
```java
|
|
|
OkHttpClient client = new OkHttpClient();
|
|
|
Request request = new Request.Builder()
|
|
|
.url("https://urz-asist.hrz.tu-chemnitz.de:/asist/rest/app/v2/feed/TUC/list")
|
|
|
.addHeader("Accept-Language", Locale.GERMANY.getISO3Language());
|
|
|
.build();
|
|
|
|
|
|
client.newCall(request).enqueue(new Callback() {
|
|
|
@Override public void onResponse(Call call, Response response) throws IOException {
|
|
|
try (ResponseBody responseBody = response.body()) {
|
|
|
...
|
|
|
}
|
|
|
}
|
|
|
|
|
|
@Override
|
|
|
public void onFailure(Call call, IOException e) {...}
|
|
|
});
|
|
|
```
|
|
|
|
|
|
## Telephone
|
|
|
Das telephone-Modul bietet, auch wenn es der Name nicht vermuten lässt, allgemeine Informationen zu Personen an.
|
|
|
### https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/telephone/tuc/search/{name}
|
|
|
Beim Aufruf dieser URL, wird eine Volltextsuche über die Namen aller Personen an der TU Chemnitz durchgeführt. Unter Verwendung des {name}-Parameters, kann die Suche gesteuert werden, indem Teile des Namens mit einem +-Zeichen separiert als Inhalt des Parameters gesetzt werden. Weithin ignoriert die Suche Groß- und Kleinschreibung.
|
|
|
|
|
|
Möchte man nach dem Vorname Otto suchen, ist folgende Adresse zu verwenden:
|
|
|
https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/telephone/tuc/search/otto
|
|
|
Sucht man nach einem Nachnamen ist das Vorgehen Analog:
|
|
|
https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/telephone/tuc/search/Normalverbraucher
|
|
|
|
|
|
Die Suche ist nicht in der Lage Nachnamen und Vorname einzeln zu suchen, wodurch dies von dem Client übernommen werden muss.
|
|
|
|
|
|
Kennt man den Vor und Nachnamen einer Person und verkettet diese, sendet der ASiST-Server ein genaueres Ergebins:
|
|
|
https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/telephone/tuc/search/otto+Normalverbraucher
|
|
|
|
|
|
## Library
|
|
|
### https://urz-asist.hrz.tu-chemnitz.de/asist/rest/app/library/tuc/findExtended
|
|
|
Über diese URL wird eine erweiterte Suche der Bücher angeboten, die mit bis zu 4 optionale Suchkriterien angesprochen werden kann. Jedes Kriterium ist als Teil des [Querry-String](https://en.wikipedia.org/wiki/Query_string) zu übermitteln, wobei der Querry-String wiederum eine Komponente der URL ist.
|
|
|
Folgende Suchkriterien können gesetzt werden:
|
|
|
* Title - String
|
|
|
* Author - String
|
|
|
* ISN - String
|
|
|
* year - Ganzzahl
|
|
|
|
|
|
```java
|
|
|
public searchBooks( String title, String author, String isn, long year ) {
|
|
|
OkHttpClient client = new OkHttpClient();
|
|
|
Request.Builder requestBuilder = new Request.Builder()
|
|
|
.url("https://urz-asist.hrz.tu-chemnitz.de:/asist/rest/app/v2/feed/TUC/list");
|
|
|
|
|
|
if( !TextUtils.isEmpty(title) ) { // Verwendung der android.text.TextUtils-Klasse
|
|
|
requestBuilder.addQueryParameter( "Title", TextUtils.isEmpty(title) );
|
|
|
}
|
|
|
|
|
|
if( !TextUtils.isEmpty(author) ) {
|
|
|
requestBuilder.addQueryParameter( "Author", TextUtils.isEmpty(author) );
|
|
|
}
|
|
|
|
|
|
if( !TextUtils.isEmpty(isn) ) {
|
|
|
requestBuilder.addQueryParameter( "ISN", TextUtils.isEmpty(isn) );
|
|
|
}
|
|
|
|
|
|
if( year > 0 ) {
|
|
|
requestBuilder.addQueryParameter( "year", String.valueOf(year) );
|
|
|
}
|
|
|
|
|
|
client.newCall(requestBuilder.build()).enqueue(new Callback() {...});
|
|
|
}
|
|
|
``` |
|
|
\ No newline at end of file |