normal
Zum Hauptinhalt springen

# 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.