Activity Streams

Mit Stud.IP Version 3.5 wurde eine neue API zum Erzeugen, Darstellen und Filtern von kontextrelevanten Aktivitäten eingeführt. Diese API kann u.a. dafür genutzt werden um Nutzern einen schnellen Überblick über die für ihn relevanten Information/Aktivitäten zu geben.

Schema "activities"

Activity Streams enthalten Objekte des Typs "activities". Diese geben enthalten eine textuelle Beschreibung der Aktivität, ein Datum, eine (etwas) detailiertere Beschreibung und die Art der Aktivität (das Verb). Aktivitäten beziehen sich auf einen Akteur (in der Regel ein Nutzer), einen Kontext, in dem sie stattfinden, und ein Objekt, auf das sie sich beziehen.

Attribute

Attribut	Beschreibung
title	knappe Beschreibung der Aktivität: "Wer tut was mit wem/was wo?"
mkdate	Datum der Aktivität
content	etwas detailiertere Beschreibung der Aktivität
verb	Art der Aktivität
activity-type	Typ der Aktivität

Die verwendeten Verben sind normiert. Der Wertebereich umfasst:

answered, attempted, attended, completed, created, deleted, edited, experienced, failed, imported, interacted, passed, shared, sent, voided

Relationen

Die Relationen sind nicht änderbar und können nur ausgelesen werden.

Relation	Beschreibung
actor	Wenn der Akteur der Aktivität ein Nutzer ist, wird mit dieser Relation auf ihn verwiesen.
context	der Kontext, in dem die Aktivität stattfindet; kann eine der folgenden sein: Veranstaltung, Einrichtung, Nutzer oder System.
object	das Objekt, mit dem die Aktivität stattfindet; falls möglich wird hier auf eine Route in der JSON:API verwiesen

Alle Aktivitäten auslesen

curl --request GET \
    --url https://example.com/jsonapi.php/v1/users/<USER-ID>/activitystream \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

fetch('https://example.com/jsonapi.php/v1/users/<USER-ID>/activitystream', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Mit dieser Route können die Aktivitäten ausgelesen werden, die für einen Nutzer sichtbar sind. Der Activity Stream wird paginiert ausgegeben. Standardmäßig werden nur Aktivitäten der letzten 6 Monate ausgegeben. Diese Einschränkung kann mit Hilfe des URL-Parameters 'filter' verändert werden.

HTTP Request

GET /users/{id}/activitystream

URL-Parameter

Parameter	Beschreibung
filter	Filtermöglichkeit der anzuzeigenden Aktivitäten (Zeit und Typ)
include	ermöglicht das Inkludieren des Akteurs, des Kontexts und des Objekts in die JSON:API-Antwort
page	Einstellmöglichkeiten zur Paginierung

URL-Parameter 'filter'

curl --request GET \
     --url 'https://example.com/jsonapi.php/v1/users/<USER-ID>/activitystream?filter\[start\]=1263078000&filter\[end\]=1409695200&filter[activity-type]=documents' \
     --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit diesem URL-Parameter kann nach Typ und Datum der Aktivitäten gefiltert werden. Möglich sind folgende Filter:

Filter	Beschreibung
filter[start]	zeitliche Beschränkung: Start des Abfrageintervalls
filter[end]	zeitliche Beschränkung: Ende des Abfrageintervalls
filter[activity-type]	nur Aktivitäten dieses Typs/dieser Typen werden zurückgeliefert

Mit Hilfe der Parameter 'start' und 'end' kann das Abfrageintervall verändert werden. Standardmäßig werden alle Aktivitäten der letzten 6 Monate bis zum aktuellen Zeitpunkt zurückgeliefert. Mit 'start' und 'end' können diese Intervallgrenzen beliebig gestaltet werden. Für diese beiden Parameter können nur ganzzahlige Werte angegeben werden, die die Anzahl der Sekunden seit dem 01.01.1970 bis zum gewünschten Zeitpunkt angeben ('unix epoch time').

Der Parameter 'activity-type' schränkt die Aktivitäten nach Typ ein. Mögliche Werte sind:

activity, documents, forum, literature, message, news, participants, schedule, wiki

Um nach mehreren Aktivitätstypen zu filtern, können mehrere dieser Typen durch Komma getrennt verwendet werden.

URL-Parameter 'include'

curl --request GET \
     --url 'https://example.com/jsonapi.php/v1/users/<USER-ID>/activitystream?include=actor,context'\
     --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Werte	Beschreibung
actor	inkludiert die Akteure der gelieferten Aktivitäten
context	inkludiert die Kontexte der gelieferten Aktivitäten
object	inkludiert die Objekte der gelieferten Aktivitäten

Der 'include'-Parameter wird der JSON:API-Spezifikation entsprechend verwendet. Es können auch mehrere Werte durch Komma getrennt angegeben werden.

Meta-Informationen

Damit klar ersichtlich ist, welche Filter für die Abfrage galten, werden diese Informationen als Top-Level-'meta'-Objekt zurückgegeben.

Authorisierung

Mit dieser Route kann nur der Nutzer selbst oder Root-Nutzer diejenigen Aktivitäten sehen, die für einen Nutzers sichtbar wären.