NAV Navbar
shell javascript

Einleitung

Willkommen bei der Dokumentation der Stud.IP-JSON:API! Mit dieser API kann auf viele Daten einer Stud.IP-Installation zugegriffen werden. Die API basiert auf der JSON:API-Spezifikation, ...

Authentifizierung

Stud.IP JSON:API verwendet drei verschiedene Verfahren um Nutzer zu authentifizieren:

Für HTTP Basic access authentication benötigt man die Zugangsdaten, die auch für ein "normales" Login verwendet werden. https://hilfe.studip.de/develop/Entwickler/RESTAPI

Nutzer

Die Nutzer der Stud.IP-Installationen können mit den folgenden Routen abgefragt werden.

Schema

Alle Nutzer werden in Stud.IP mit diesem Schema abgebildet. Die id entspricht der in Stud.IP verwendeten user_id. Der Typ ist users.

Attribute

Attribut Beschreibung
username der Nutzername
formatted-name der formatierte Echtname des Nutzers
family-name der Nachname des Nutzers
given-name der Vorname des Nutzers
name-prefix evtl. vorangestellte Titel
name-suffix evtl. nachgestellte Titel
permission die globale Berechtigungsstufe
email die E-Mail-Adresse des Nutzers
phone die Telefonnummer des Nutzers
homepage die URL der Homepage des Nutzers
address die private Adresse des Nutzers

Die Berechtigungsstufe kann eine der folgenden sein: root, admin, dozent, tutor, autor

Die Sichtbarkeit der Attribute "phone", "homepage", "address" folgt den Sichtbarkeitseinstellungen, die der Nutzer vorgenommen hat.

Relationen

Relation Beschreibung
activitystream ein Link zum activity stream des Nutzers
blubber-postings die Blubber des Nutzers
contacts die Kontakte des Nutzers
courses die Veranstaltungen der Nutzers (als Dozent)
course-memberships die Veranstaltungen der Nutzers (als Teilnehmer)
events der Terminkalender des Nutzers
institute-memberships die Institute der Nutzers
schedule der Stundenplan des Nutzers

Alle Nutzer

curl --request GET \
    --url https://example.com/users \
    --header "Authorization: Basic `echo -ne "root@studip:testing" | base64`" \

Der Request liefert JSON ähnlich wie dieses:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 30,
      "total": 5
    }
  },
  "links": {
    "first": "/?page[offset]=0&page[limit]=30",
    "last": "/?page[offset]=0&page[limit]=30"
  },
  "data": [
    {
      "type": "users",
      "id": "76ed43ef286fb55cf9e41beadb484a9f",
      "attributes": {
        "username": "root@studip",
        "formatted-name": "Root Studip",
        "family-name": "Studip",
        "given-name": "Root",
        "name-prefix": "",
        "name-suffix": "",
        "permission": "root",
        "email": "root@localhost",
        "phone": null,
        "homepage": null,
        "address": null
      },
      "relationships": {
        "activitystream": {
          "links": {
            "related": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f/activitystream"
          }
        },
        "blubber-postings": {
          "links": {
            "related": "jsonapi.php/v1/blubber-postings?filter[user]=76ed43ef286fb55cf9e41beadb484a9f"
          }
        },
        "contacts": {
          "links": {
            "related": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f/contacts"
          }
        },
        "courses": {
          "links": {
            "related": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f/courses"
          }
        },
        "course-memberships": {
          "links": {
            "related": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f/course-memberships"
          }
        },
        "events": {
          "links": {
            "related": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f/events"
          }
        },
        "institute-memberships": {
          "links": {
            "related": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f/institute-memberships"
          }
        },
        "schedule": {
          "links": {
            "related": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f/schedule"
          }
        }
      },
      "links": {
        "self": "jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f"
      },
      "meta": [

] }, "[...]" ] }

Dieser Endpoint liefert alle Nutzer im Stud.IP, die der JSON:API-Nutzer mit seinen credentials auch im Stud.IP selbst sehen darf. Die Ausgabe erfolgt paginiert und kann durch Angabe von Offset und Limit weitergeblättert werden.

HTTP Request

GET /users

Query-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset
page[limit] 30 das Limit

Autorisierung

Diese Route kann nur von Nutzern der Rechtestufe "root" verwendet werden.

Sich selbst auslesen

curl --request GET \
    --url https://example.com/users/me \
    --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`"

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "users",
    "id": "205f3efb7997a0fc9755da2b535038da",
    "attributes": {
      "username": "test_dozent",
      "formatted-name": "Testaccount Dozent",
      "family-name": "Dozent",
      "given-name": "Testaccount",
      "name-prefix": "",
      "name-suffix": "",
      "permission": "dozent",
      "email": "dozent@studip.de",
      "phone": null,
      "homepage": null,
      "address": null
    },
    "relationships": {
      "activitystream": {
        "links": {
          "related": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da/activitystream"
        }
      },
      "blubber-postings": {
        "links": {
          "related": "jsonapi.php/v1/blubber-postings?filter[user]=205f3efb7997a0fc9755da2b535038da"
        }
      },
      "contacts": {
        "links": {
          "related": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da/contacts"
        }
      },
      "courses": {
        "links": {
          "related": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da/courses"
        }
      },
      "course-memberships": {
        "links": {
          "related": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da/course-memberships"
        }
      },
      "events": {
        "links": {
          "related": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da/events"
        }
      },
      "institute-memberships": {
        "links": {
          "related": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da/institute-memberships"
        }
      },
      "schedule": {
        "links": {
          "related": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da/schedule"
        }
      }
    },
    "links": {
      "self": "jsonapi.php/v1/users/205f3efb7997a0fc9755da2b535038da"
    },
    "meta": [

    ]
  }
}

Mit diesem Endpoint bekommt man denjenigen Stud.IP Nutzer, der autorisiert auf diesen Endpoint zugreift – also sich selbst.

HTTP Request

GET /users/me

Query-Parameter

Es werden keine Query-Parameter unterstützt.

Autorisierung

Diese Route kann von jedem autorisierten Nutzer verwendet werden.

Einen Nutzer auslesen

curl --request GET \
    --url https://example.com/users/<ID> \
    --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`"

Diese Route liefert einen beliebigen Nutzer zurück. Unsichtbare Nutzer können sich allerdings nur selbst sehen.

HTTP Request

GET /users/{id}

Query-Parameter

Es werden keine Query-Parameter unterstützt.

Autorisierung

Man kann sich selbst sehen. "root" darf jeden Nutzer sehen. Gesperrte und unsichtbare Nutzer sind ansonsten nicht sichtbar.

Einen Nutzer löschen

curl --request DELETE \
    --url https://example.com/users/<ID> \
    --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`"

Diese Route löscht einen beliebigen Nutzer.

HTTP Request

DELETE /users/{id}

Query-Parameter

Es werden keine Query-Parameter unterstützt.

Autorisierung

Diese Route ist nur aktiviert, wenn die Stud.IP-Konfiguration "JSONAPI_DANGEROUS_ROUTES_ALLOWED" gesetzt ist.

Ist das der Fall, dürfen Nutzer der Rechtestufe "root" andere Nutzer löschen. Man kann sich selbst nicht löschen.

GET /users/{id}/institute-memberships

curl --request GET \
    --url https://example.com/users/<ID>/institute-memberships \
    --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`"

Mit dieser Route erhält man die Mitgliedschaften in Einrichtungen eines Nutzers.

HTTP Request

GET http://example.com/api/users/{id}/institute-memberships

Query-Parameter

Es werden keine Query-Parameter unterstützt.

Autorisierung

Ein Nutzer kann nur die eigenen Mitgliedschaften in Einrichtungen einsehen.

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/users/<USER-ID>/activitystream \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/users/<USER-ID>/activitystream', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

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/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, blubber, 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/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.

Ankündigungen (News)

Schema "news"

Ankündigungen bestehen aus ihrem Inhalt und einigen Meta-Daten. Die Dauer der Sichtbarkeit einer Anküdnigung wird durch ihre Attribute publication-start und end bestimmt (siehe Relationen).

Attribute

Attribut Beschreibung
title Name einer news
content Inhalt einer News
mkdate Erstellungs-Datum einer News
chdate Datum der letzten Änderung
publication-start Start der Sichtbarkeit für den Nutzerkreis einer News
publication-end Ende der Sichtbarkeit für den Nutzerkreis einer News
comments-allowed Bestimmung, ob Kommentare erlaubt sind (Boolean)

Ein Beispiel zum erstellen einer News anhand des Schemas folgt in News anlegen.

Relationen

Relation Beschreibung
author Ersteller einer News
ranges global, institute, semester, course, users

Der Range einer News gibt an wo sie publiziert wird und somit auch für wen sie sichtbar ist.

Schema "comments"

Kommentare werden in Stud.IP an eine Ankündigung angehangen, wenn der Ersteller der News die Erlaubnis vergeben hat.

Attribute

Attribut Beschreibung
content Inhalt eines Kommentars
mkdate Erstellungs-Datum
chdate Datum der letzten Änderung

Relationen

Relation Beschreibung
author Der Ersteller des Kommentars
news Die kommentierte News

News anlegen

Das Anlegen einer News ist in verschiedenen Kontexten möglich. Sie kann global als systemweite News, kursintern oder nutzerbezogen angelegt werden.

Eine globale News anlegen

Route

POST /news

Autorisierung

Die Erstellung einer globalen News erfordern zur Zeit noch Root-Rechte. Es wird diskutiert ob hier Adminrechte reichen.

   curl --request POST \
       --url https://example.com/news \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "root@studip:testing" | base64`" \
       --data
       '{"data": {"type": "news","attributes": {"title": "Neue News","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine neue News sieht das Tageslicht."}}}'

Eine Kurs-News anlegen

POST /courses/{id}/news

   curl --request POST \
       --url https://example.com/courses/<COURSE-ID>/news \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`" \
       --data
       '{"data": {"type": "news","attributes": {"title": "Neue News","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine neue News sieht das Tageslicht."}}}'
Parameter Beschreibung
id Die ID des Kurses

Autorisierung

Der Nutzer muss mindestens Dozenten- oder Adminrechte innerhalb des Kurses haben.

Eine Nutzer-News anlegen

POST /users/{id}/news

   curl --request POST \
       --url https://example.com/users/<USER-ID>/news \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
       --data
       '{"data": {"type": "news","attributes": {"title": "Neue News","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine neue News sieht das Tageslicht."}}}'
Parameter Beschreibung
id Die ID des Users

Autorisierung

Der Nutzer muss mindestens User-Rechte haben.

Einen Kommentar anlegen

POST /news/{id}/comments

   curl --request POST \
       --url https://example.com/news/<NEWS-ID>/comments \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`" \
       --data
       '{"data": {"type": "comments","attributes": {"content": "Ein Kommentar wurde geupdatet"}}}'

### Autorisierung Der Nutzer muss mindestens User-Rechte haben.

Parameter Beschreibung
id Die ID der News

Eine News ändern

PATCH /news/{id}

Parameter Beschreibung
id Die ID der News

Die Data-Felder beim Update einer News sind optional.

  curl --request PATCH \
      --url https://example.com/news/<NEWS-ID> \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data
      '{"data": {"type": "news","attributes": {"title": "Aenderungen","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine News wurde geaendert."}}}'

Autorisierung

Der Nutzer muss Inhaber der News sein oder die entsprechenden Root-Rechte besitzen.

Eine News ansehen

GET /news/{id}

Parameter Beschreibung
id Die ID der News
  curl --request GET \
      --url https://example.com/news/<NEWS-ID> \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Autorisierung

Der Nutzer muss Inhaber der News sein oder die entsprechenden Range-Rechte besitzen.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "news",
    "id": "6a8be7e4859e9c781ecc47a2c3498435",
    "attributes": {
      "title": "A testing title",
      "content": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
      "mkdate": "2019-04-23T12:10:26+02:00",
      "chdate": "2019-04-23T12:10:26+02:00",
      "publication-start": "2019-04-23T12:10:26+02:00",
      "publication-end": "2019-05-07T12:10:26+02:00",
      "comments-allowed": true
    },
    "relationships": {
      "author": {
        "data": {
          "type": "users",
          "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
        },
        "links": {
          "related": "jsonapi.php/v1/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
        }
      },
      "ranges": {
        "data": [

], "links": { "self": "jsonapi.php/v1/news/6a8be7e4859e9c781ecc47a2c3498435/relationships/ranges" } } }, "links": { "self": "jsonapi.php/v1/news/6a8be7e4859e9c781ecc47a2c3498435" } } }

Alle Kurs-News

GET /courses/{id}/news

Parameter Beschreibung
id Die ID des Kurses
  curl --request GET \
      --url https://example.com/course/<COURSE-ID>/news \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Autorisierung

Der Nutzer muss mindestens Teilnehmer des Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "news",
    "id": "6a8be7e4859e9c781ecc47a2c3498435",
    "attributes": {
      "title": "A testing title",
      "content": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
      "mkdate": "2019-04-23T12:10:26+02:00",
      "chdate": "2019-04-23T12:10:26+02:00",
      "publication-start": "2019-04-23T12:10:26+02:00",
      "publication-end": "2019-05-07T12:10:26+02:00",
      "comments-allowed": true
    },
    "relationships": {
      "author": {
        "data": {
          "type": "users",
          "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
        },
        "links": {
          "related": "jsonapi.php/v1/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
        }
      },
      "ranges": {
        "data": [

], "links": { "self": "jsonapi.php/v1/news/6a8be7e4859e9c781ecc47a2c3498435/relationships/ranges" } } }, "links": { "self": "jsonapi.php/v1/news/6a8be7e4859e9c781ecc47a2c3498435" } } }

Alle Nutzer-News

GET /users/{id}/news

Parameter Beschreibung
id Die ID des Nutzers
   curl --request GET \
       --url https://example.com/user/<USER-ID>/news \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Autorisierung

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "news",
    "id": "0e8df7da383d7515c4dc081bfe889897",
    "attributes": {
    "title": "Neue News",
    "content": "Eine neue News sieht das Tageslicht.",
    "mkdate": "2018-06-19T16:08:51+02:00",
    "chdate": "2018-08-15T14:22:38+02:00",
    "publication-start": "2018-06-19T16:08:51+02:00",
    "publication-end": "2066-12-05T15:08:51+01:00",
    "comments-allowed": true
    },
    "relationships": {
      "author": {
        "data": {
          "type": "users",
          "id": "76ed43ef286fb55cf9e41beadb484a9f"
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
        }
      },
      "ranges": {
        "data": [
        {
          "type": "users",
          "id": "1b7d3834e42c1569947e0eab7b63ed19"
        }
        ],
          "links": {
          "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897/relationships/ranges"
          }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897"
    }
  }
}

Alle News-Kommentare

GET /news/{id}/comments

Parameter Beschreibung
id Die ID einer News

Alle globalen News

GET /studip/news

   curl --request GET \
       --url https://example.com/user/studip/news \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Autorisierung

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "news",
    "id": "0e8df7da383d7515c4dc081bfe889897",
    "attributes": {
    "title": "Globale News",
    "content": "Eine neue News sieht das Tageslicht.",
    "mkdate": "2018-06-19T16:08:51+02:00",
    "chdate": "2018-08-15T14:22:38+02:00",
    "publication-start": "2018-06-19T16:08:51+02:00",
    "publication-end": "2066-12-05T15:08:51+01:00",
    "comments-allowed": true
    },
    "relationships": {
      "author": {
        "data": {
          "type": "users",
          "id": "76ed43ef286fb55cf9e41beadb484a9f"
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
        }
      },
      "ranges": {
        "data": [
        {
          "type": "global",
          "id": "studip"
        }
        ],
          "links": {
          "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897/relationships/ranges"
          }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897"
    }
  }
}

Alle News des aktuell eingeloggten Nutzers abrufen

GET /news

  curl --request GET \
      --url https://example.com/news \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Autorisierung

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "news",
    "id": "0e8df7da383d7515c4dc081bfe889897",
    "attributes": {
    "title": "Neue News",
    "content": "Eine neue News sieht das Tageslicht.",
    "mkdate": "2018-06-19T16:08:51+02:00",
    "chdate": "2018-08-15T14:22:38+02:00",
    "publication-start": "2018-06-19T16:08:51+02:00",
    "publication-end": "2066-12-05T15:08:51+01:00",
    "comments-allowed": true
    },
    "relationships": {
      "author": {
        "data": {
          "type": "users",
          "id": "76ed43ef286fb55cf9e41beadb484a9f"
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
        }
      },
      "ranges": {
        "data": [
        {
          "type": "users",
          "id": "1b7d3834e42c1569947e0eab7b63ed19"
        }
        ],
          "links": {
          "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897/relationships/ranges"
          }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897"
    }
  }
}

Eine News löschen

DELETE /news/{id}

Parameter Beschreibung
id Die ID der News

Authorisierung

Diese Route kann nur vom Nutzer der betreffenden Nachrichten genutzt werden.

   curl --request DELETE \
       --url https://example.com/news/<NEWS-ID> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

### Autorisierung

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

Einen Kommentar löschen

DELETE /comments/{id}

Parameter Beschreibung
id Die ID eines Kommentars
   curl --request DELETE \
       --url https://example.com/comments/studip/news \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Alle News-Ranges

GET /news/{id}/relationships/ranges

see http://jsonapi.org/format/#fetching-relationships

News-Ranges setzen

PATCH /news/{id}/relationships/ranges

see http://jsonapi.org/format/#crud-updating-to-many-relationships

News-Ranges hinzufügen

POST /news/{id}/relationships/ranges

see http://jsonapi.org/format/#crud-updating-to-many-relationships

News-Ranges löschen

DELETE /news/{id}/relationships/ranges

see http://jsonapi.org/format/#crud-updating-to-many-relationships

Blubber

Schema 'blubber-postings'

Der Inhalt wird als plain-text und html gespeichert. Meta-Daten geben Informationen über den Zeitpunkt und das Thema einer Nachricht.

Attribute

Attribut Beschreibung
context-type die Art des Kontexts; Veranstaltung ("course"), Öffentlich ("global") oder Nutzer ("user")
content der Text des Blubber-Beitrags; kann Stud.IP-Markup enthalten
content-html der Text des Blubber-Beitrags; als HTML formatiert
mkdate Anlegedatum
chdate Datum der letzten Änderung
discussion-time Datum der letzten Aktivität
tags eine Liste von Tags

Relationen

Relation Beschreibung
author Verfasser der Nachricht
comments Untergeordnete Blubber
context Wem wird der Blubber angezeigt: users, courses, public
mentions Thema eines Blubber-Eintrags
parent Übergeordneter Blubber-Eintrag
resharers

Alle Beiträge

curl --request GET \
    --url https://example.com/blubber-postings \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/blubber-postings', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Es werden alle Blubber-Beiträge, die man im Stud.IP sehen könnte, angezeigt.

HTTP Request

GET /blubber-postings

URL-Parameter

Parameter Beschreibung
filter Filtermöglichkeit der anzuzeigenden Blubber-Beiträge
include abhängige Ressourcen, die auch zurückgeliefert werden (JSON:API-Spezifikation)
page Einstellmöglichkeiten zur Paginierung

URL-Parameter 'filter'

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

Beispiel-Url: "https://example.com/blubber-postings?filter[user]=205f3efb7997a0fc9755da2b535038da"

Filter Beschreibung
filter[course] Filtert Blubber-Einträge für eine Veranstaltung
filter[user] Filter Blubber-Einträge für einen Nutzer

URL-Parameter 'include'

Fügt folgende Attribute in die Ausgabe hinzu.

Wert Beschreibung
author Den Verfasser eines Blubbers
comments Angehangene Blubber
context Wem wird der post angezeigt (users, courses, public)
mentions
resharers

Beitrag auslesen

Einen gezielten Blubber-Eintrag auslesen.

HTTP Request

GET /blubber-postings/{id}

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Beitrag anlegen

   curl --request POST \
       --url https://example.com/blubber-postings \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
       --data \
       '{"data":{"type":"blubber-postings","attributes":{"context-type":"course","content":"Ein neuer blubberpost"},"relationships":{"context":{"data":{"type":"courses","id":"<CID>"}}}}}'

Mit dieser Route kann ein Blubber-Beitrag angelegt werden. Dies kann ein öffentlicher oder privater Beitrag sein, aber auch Blubber in Veranstaltungen können darüber angelegt werden.

HTTP Request

POST /blubber-postings

HTTP Request Body

Im Request-Body muss der neue Beitrag als resource object vom Typ "blubber-postings" sein.

Notwendig sind die Attribute "content" und "context-type".

Abhängig vom Wert des Attributs "context-type", muss außerdem eine "context"-Relation angegeben werden.

Hat dieses Attribut den Wert "course", muss als "context"-Relation eine Veranstaltung als resource identifiert angegeben werden.

Parameter

Bei diesem Request sind keine Parameter notwendig.

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

Beitrag editieren

Aktualisiert einen Blubber-Beitrag.

HTTP Request

PATCH /blubber-postings/{id}

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Der Sender des Requests muss Besitzer des Blubber-Beitrags oder Root sein.

   curl --request PATCH \
       --url https://example.com/blubber-postings/<blubber-id> \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "root@studip:testing" | base64`" \
       --data
       '{"data":{"type":"blubber-postings","attributes":{"context-type":"course","content":"Ein veränderter blubberpost"}, "relationships":{"context":{"data":{"type":"courses","id":"a07535cf2f8a72df33c12ddfa4b53dde"}}}}}'

Beitrag löschen

Löscht einen Blubber-Eintrag.

HTTP Request

DELETE /blubber-postings/{id}

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Der Sender des Requests muss Besitzer des Blubber-Beitrags oder Root sein.

   curl --request DELETE \
       --url https://example.com/blubber-postings/<blubber-id> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Relation 'author'

Gibt den Author eines Blubber-Posts zurück.

HTTP Request

GET /blubber-postings/{id}/relationships/author

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/relationships/author \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Kommentare eines Blubber-Beitrags

Gibt alle Kommentare eines Blubber-Beitrags zurück.

HTTP Request

GET /blubber-postings/{id}/comments

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/comments \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Beitrag kommentieren

Erstellt einen Kommentar zu einem Blubber-Beitrag.

HTTP Request

POST /blubber-postings/{id}/comments

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request POST \
       --url https://example.com/blubber-postings/<posting-id>/comments \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "root@studip:testing" | base64`" \
       --data
       '{"data": {"type": "blubber-postings","attributes": {"content": "Ein neuer blubberkommentar"}}}'

Relation 'comments'

HTTP Request

GET /blubber-postings/{id}/relationships/comments

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/relationships/comments \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Relation 'context'

Gibt den Scope (Sichtbarkeit) eines Blubber-Beitrags zurück.

HTTP Request

GET /blubber-postings/{id}/relationships/context

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/relationships/context \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Erwähnungen eines Beitrags

Gibt an, ob und in welchen Beiträgen eine Referenz zu diesem Beitrag gibt.

HTTP Request

GET /blubber-postings/{id}/mentions

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/mentions \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Relation 'mentions'

Gibt die Referenz der Beiträge zurück, in denen dieser Beitrag erwähnt wird.

HTTP Request

GET /blubber-postings/{id}/relationships/mentions

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/relationships/mentions \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Relation 'resharers'

Gibt die Referenz von Usern zurück, die diesen Beitrag geteilt haben.

HTTP Request

GET /blubber-postings/{id}/relationships/resharers

Parameter

Parameter Beschreibung
id ID des Blubber-Posts

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/relationships/resharers \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Blubber-Stream auslesen

Gibt eine Folge von Blubber-Einträgen zurück.

GET /blubber-streams/{id}

Parameter

Parameter Beschreibung
id ID des Blubber-Streams

Authorisierung

Diese Route kann von allen Nutzern verwendet werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/blubber-streams/<stream-id> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Dateibereich v3.5

In Stud.IP hat jede Einrichtung und jede Veranstaltung einen eigenen Dateibereich. Dateibereiche sind (spezielle) Ordner. Ordner können Dateien und Ordner enthalten, in denen sich wiederum Dateien und Ordner befinden können.

Es gibt verschiedene Arten von Ordnern, die sich in der Regel darin unterscheiden, wer sie sehen kann und wer Lese- und/oder Schreibzugriff auf diese Ordner hat.

Im Dateibereich von Stud.IP v3.5 werden drei Arten von Entitäten verwendet. Es gibt Dokumente (type=documents), Ordner (type=document-folders) und Lizenzen (type=document-licenses).

Schema "documents"

In Stud.IP kann man Dokumente auf zwei Weisen einbinden. Zum einen können Dokumente hochgeladen werden. Zum anderen kann auch einfach eine URL hinterlegt werden, die via Stud.IP-Proxy an die Nutzer herausgegeben wird. Dokumente bestehen sowohl aus ihren Metadaten (wie Name und Beschreibung), als auch aus ihrem eigentlichen Inhalt.

TODO: download-link, url

Relationen

Derzeit können die Relationen nur ausgelesen, aber nicht verändert werden.

Relation Beschreibung
license die Lizenz des Dokuments
owner der Besitzer des Dokuments
parent Speicherort des Dokuments; entweder ein Ordner oder eine Nachricht
range Link zum Dateibereich, in dem sich das Dokument befindet; entweder eine Veranstaltung oder eine Einrichtung

Attribute

Attribut Beschreibung
name Name des Dokuments
description Beschreibung des Dokuments
filename Dateiname des Dokuments
mkdate Anlegedatum
chdate Datum der letzten Änderung
filesize Größe der Datei in Bytes
downloads Anzahl der bisherigen Downloads
priority Ordnungsnummer; dient der Sortierung in Stud.IP

Meta-Informationen

Ein Dokument liefert als Meta-Information die URL zum Abrufen und Aktualisieren seines Inhalts zurück.

Schema "document-folders"

Ordner enthalten Dokumente und können im Zugriff beschränkt werden

Attribute

Attribut Beschreibung
name Name des Ordners
description Beschreibung des Ordners
permission Zugriffsbeschränkung des Ordners; ein String, der maximal aus "frwx" besteht
mkdate Anlegedatum
chdate Datum der letzten Änderung
priority Ordnungsnummer; dient der Sortierung in Stud.IP

Die Zugriffsbeschränkung ist als String kodiert, ähnlich wie im Dateisystem eines Betriebsystems. Maximal besteht es aus den Buchstaben "frwx". Dabei bedeuten die Buchstaben folgendes:

Buchstabe Bedeutung
f Ordner erstellen (Alle Nutzer können Ordner erstellen)
r Lesen (Dateien können heruntergeladen werden)
w Schreiben (Dateien können heraufgeladen werden)
x Sichtbarkeit (Ordner wird angezeigt)

Relationen

Derzeit können die Relationen nur ausgelesen, aber nicht verändert werden.

Relation Beschreibung
documents die im Ordner liegenden Dokumente
document-folders der im Ordner liegenden Ordner
owner der Besitzer des Ordners
parent der übergeordnete Ordner des Ordners, falls es einen gibt
range Link zum Dateibereich, in dem sich das Dokument befindet; entweder eine Veranstaltung oder eine Einrichtung

Schema "document-licenses"

Dokumenten können Lizenzen zugeordnet sein.

Attribut Beschreibung
name Name der Lizenz
description Beschreibung der Lizenz
student-description TODO
protected TODO

Lizenzen haben keine Relationen.

Alle Dokumente einer Veranstaltung/Einrichtung

curl --request GET \
    --url https://example.com/courses/<COURSE-ID>/documents \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/courses/<COURSE-ID>/documents', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 30,
      "total": 1
    }
  },
  "links": {
    "first": "/?page[offset]=0&page[limit]=30",
    "last": "/?page[offset]=0&page[limit]=30"
  },
  "data": [
    {
      "type": "documents",
      "id": "210ea083325e12fdb2dd6eaa534d0570",
      "attributes": {
        "name": "test.json",
        "description": "Eine Beschreibung",
        "filename": "test.json",
        "mkdate": "2018-01-24T09:52:13+01:00",
        "chdate": "2018-01-24T09:52:13+01:00",
        "filesize": 17,
        "downloads": 0,
        "priority": 0
      },
      "relationships": {
        "parent": {
          "data": {
            "type": "document-folders",
            "id": "b0243fbbd542ffa5d00eca4791540f03"
          },
          "links": {
            "related": "https://example.com/document-folders/b0243fbbd542ffa5d00eca4791540f03"
          }
        },
        "range": {
          "data": {
            "type": "courses",
            "id": "a07535cf2f8a72df33c12ddfa4b53dde"
          },
          "links": {
            "related": "https://example.com/courses/a07535cf2f8a72df33c12ddfa4b53dde"
          }
        },
        "owner": {
          "data": {
            "type": "users",
            "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
          },
          "links": {
            "related": "https://example.com/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
          }
        }
      },
      "links": {
        "self": "https://example.com/documents/210ea083325e12fdb2dd6eaa534d0570"
      },
      "meta": {
        "download-url": "https://example.com/documents/210ea083325e12fdb2dd6eaa534d0570/content"
      }
    }
  ]
}

Wenn der Dateibereich in einer Veranstaltung aktiviert ist, kann man mit dieser Route alle Dokumente einer Veranstaltung abfragen.

HTTP Request

GET /jsonapi/courses/{id}/documents

URL-Parameter

Parameter Beschreibung
id die ID der Veranstaltung

Authorisierung

Diese Route kann von allen Nutzern verwendet werden, die Zugriff auf die entsprechende Veranstaltung oder Einrichtung haben.

Alle Ordner einer Veranstaltung/Einrichtung

curl --request GET \
    --url https://example.com/courses/<COURSE-ID>/document-folders \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/courses/<COURSE-ID>/document-folders', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 30,
      "total": 1
    }
  },
  "links": {
    "first": "/?page[offset]=0&page[limit]=30",
    "last": "/?page[offset]=0&page[limit]=30"
  },
  "data": [
    {
      "type": "document-folders",
      "id": "4e06de84a2812908879eef42c9d652d9",
      "attributes": {
        "name": "Allgemeine Dateien",
        "description": "Allgemeine Beschreibung",
        "permission": "frwx",
        "mkdate": "2018-01-24T12:08:38+01:00",
        "chdate": "2018-01-24T12:08:38+01:00",
        "priority": 0
      },
      "relationships": {
        "documents": {
          "links": {
            "related": "https://example.com/document-folders/4e06de84a2812908879eef42c9d652d9/documents"
          }
        },
        "document-folders": {
          "links": {
            "related": "https://example.com/document-folders/4e06de84a2812908879eef42c9d652d9/document-folders"
          }
        },
        "owner": {
          "data": {
            "type": "users",
            "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
          },
          "links": {
            "related": "https://example.com/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
          }
        },
        "range": {
          "data": {
            "type": "courses",
            "id": "a07535cf2f8a72df33c12ddfa4b53dde"
          },
          "links": {
            "related": "https://example.com/courses/a07535cf2f8a72df33c12ddfa4b53dde"
          }
        }
      },
      "links": {
        "self": "https://example.com/document-folders/4e06de84a2812908879eef42c9d652d9"
      }
    }
  ]
}

Wenn der Dateibereich in einer Veranstaltung aktiviert ist, kann man mit dieser Route alle Ordner einer Veranstaltung abfragen, auf die man Zugriff hat.

HTTP Request

GET /(courses|institutes)/{id}/document-folders

URL-Parameter

Parameter Beschreibung
id die ID der Veranstaltung

Authorisierung

Diese Route kann von allen Nutzern verwendet werden, die Zugriff auf die entsprechende Veranstaltung oder Einrichtung haben. Es werden aber lediglich diejenigen Ordner gezeigt, die der Nutzer verwenden kann.

Ein Dokument auslesen

curl --request GET \
    --url https://example.com/documents/{id} \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/documents/{id}', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "documents",
    "id": "81a3eec43cf70a11b9926649f19b3988",
    "attributes": {
      "name": "test.json",
      "description": "Eine Beschreibung",
      "filename": "test.json",
      "mkdate": "2018-01-24T13:36:18+01:00",
      "chdate": "2018-01-24T13:36:18+01:00",
      "filesize": 17,
      "downloads": 0,
      "priority": 0
    },
    "relationships": {
      "parent": {
        "data": {
          "type": "document-folders",
          "id": "dab61ecc743f55662311bec4afcfc7e9"
        },
        "links": {
          "related": "https://example.com/document-folders/dab61ecc743f55662311bec4afcfc7e9"
        }
      },
      "range": {
        "data": {
          "type": "courses",
          "id": "a07535cf2f8a72df33c12ddfa4b53dde"
        },
        "links": {
          "related": "https://example.com/courses/a07535cf2f8a72df33c12ddfa4b53dde"
        }
      },
      "owner": {
        "data": {
          "type": "users",
          "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
        },
        "links": {
          "related": "https://example.com/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
        }
      }
    },
    "links": {
      "self": "https://example.com/documents/81a3eec43cf70a11b9926649f19b3988"
    },
    "meta": {
      "download-url": "https://example.com/documents/81a3eec43cf70a11b9926649f19b3988/content"
    }
  }
}

Mit dieser Route kann man ein einzelnes Dokument auslesen, wenn man darauf Zugriff hat.

HTTP Request

GET https://example.com/documents/{id}

URL-Parameter

Parameter Beschreibung
id die ID des Dokuments

Authorisierung

Autoren sehen nur eingeschränkt Dokumente in ihren Veranstaltungen (nach den üblichen Stud.IP-Regeln). Tutoren und Dozenten haben Zugriff auf alle Dokumente ihrer Veranstaltung; Administratoren entsprechend auf Dokumente, die zu Veranstaltungen ihrer Einrichtungen gehören; Root natürlich auf alle.

Eine Dokument-Datei herunterladen

curl --request GET \
    --url https://example.com/documents/{id} \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/documents/{id}/content', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert in der Regel kein JSON. (Es sei denn, dass das Dokument ein JSON-Objekt war.)

Mit dieser Route kann man die tatsächliche Datei herunterladen. Diese wird in der Regel nicht als JSON ausgeliefert.

HTTP Request

GET https://example.com/documents/{id}/content

URL-Parameter

Parameter Beschreibung
id die ID des Dokuments

Authorisierung

Autoren können nur eingeschränkt Dokumente in ihren Veranstaltungen herunterladen (nach den üblichen Stud.IP-Regeln). Tutoren und Dozenten haben Zugriff auf alle Dokumente ihrer Veranstaltung; Administratoren entsprechend auf Dokumente, die zu Veranstaltungen ihrer Einrichtungen gehören; Root natürlich auf alle.

Eine Dokument-Datei aktualisieren

curl --request POST --form 'file=@die-aktuelle-datei.jpg' \
     --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`" \
     --url "https://example.com/documents/{id}/content"

Mit dieser Route kann man den Inhalt eines vorhandenen Dokuments aktualisieren.

Dazu sendet man einen POST-Request an dieselbe Route, von der aus man auch den Inhalt herunterladen würde.

HTTP Request

POST https://example.com/documents/{id}/content

URL-Parameter

Parameter Beschreibung
id die ID des Dokuments

Authorisierung

Die Berechtigungsregeln zum Aktualisieren des Inhalts eines Dokuments sind komplex. In der Regel darf man seine eigenen Dokumente und Tutoren und Dozenten die meisten anderen Dokumente aktualisieren. Die Berechtigungsregeln entsprechen dem Verhalten, das Stud.IP über die Web-Oberfläche zeigt.

Ein Dokument erstellen

Ein Dokument wird immer in einem Ordner erstellt. Da wie oben beschrieben Dokumente aus Metadaten und Inhalt bestehen, muss das Anlegen einer Datei in zwei Schritten passieren. Dazu kann entweder a.) zuerst der Inhalt hochgeladen werden und dann die Metadaten (wie Beschreibung und Lizenz) angepasst werden oder b.) erst die Datei mit den Metadaten erstellt werden und nachträglich der Inhalt hochgeladen werden.

Variante a.

curl --request POST --form 'file=@eine-neue-datei.jpg' \
     --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`" \
     --url "https://example.com/document-folders/{id}/documents"

Zuerst sendet man einen POST-Request mit Content-Type: multipart/form-data und der Datei im Request-Body an die unten angegebene URL.

Man erhält im Erfolgsfall einen Status-Code 201 und einen Location-Header, der einen zum neu erstellten Dokument in die JSON:API bringt.

Der Dateiname wird standardmäßig aus dem Upload genommen und auch für den Namen der Datei verwendet.

Will man einen anderen Dateinamen verwenden, kann man einen HTTP-Header wie: Slug: neuer-dateiname.txt verwenden.

Über die URL aus dem erhaltenen Location-Header erhält man die JSON:API-Repräsentation der hochgeladenen Datei.

Nun können mit einem (JSON:API-typischen) PATCH-Request an diese Route Modifikationen an den Metadaten (wie Beschreibung usw.) vorgenommen werden.

Variante b.

curl --request POST \
    --url https://example.com/document-folders/{id}/documents \
    --header "Content-Type: application/vnd.api+json" \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --data '{"data": { "type": "documents", "attributes": { "name": "iason.txt", "description": "Iasons Lebenslauf", "filename": "iason.txt"}}}'

Zunächst sendet man einen POST-Request mit Content-Type: application/vnd.api+json an die unten angegebene URL.

Im Request-Body muss dann eine JSON:API-typische Repräsentation des neuen Dokuments enthalten sein. Im Erfolgsfall erhält man dann eine Repräsentation der neu angelegten Datei, die aber derzeit noch keinen Inhalt hat.

Daher muss der Inhalt in einem zweiten Request hochgeladen werden. Dazu wird unter "Eine Dokument-Datei aktualisieren" beschrieben ein POST-Request an die content-URL geschickt.

HTTP Request

POST https://example.com/document-folders/{id}/documents

URL-Parameter

Parameter Beschreibung
id die ID des Dokuments

HTTP Request Body

Im Request-Body muss das neue Dokument als ein einziges resource object enthalten sein. Das resource object muss im type-Attribut "documents" enthalten und darf keine id haben.

// Ein Beispiel:

POST /document-folders/{id}/documents HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "documents",
    "attributes": {
      "name": "Der Name des Dokuments",
      "description": "Die Beschreibung des Dokuments",
      "filename": "test-file.txt"
    }
}

Authorisierung

Die Berechtigungen zum Anlegen eines Dokuments in einem Ordner sind komplex und entsprechend denen, die in der Web-Oberfläche von Stud.IP verwendet werden.

Ein Dokument löschen

curl --request DELETE \
    --url https://example.com/documents/{id} \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/documents/{id}', {
    method: 'DELETE',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert nichts zurück.

Mit dieser Route kann man eine Datei löschen. Gemäß JSON-API-Spezifikation antwortet der Server im Erfolgsfall mit einem Status-Code 204.

HTTP Request

DELETE https://example.com/documents/{id}

URL-Parameter

Parameter Beschreibung
id die ID des Dokuments

Authorisierung

Eigene Dateien können gelöscht werden. Ansonsten gelten die für die Veranstaltung bzw. Einrichtungen geltenden Einschränkungen ganz genau wie im üblichen Stud.IP.

Ein Dokument ändern

curl --request PATCH \
    --url https://example.com/documents/{id} \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/documents/{id}', {
    method: 'PATCH',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Die Attribute name und description und die license-Relation eines Dokuments sind durch einen PATCH-Request änderbar. Der Request-Body enthält dazu ein geeignetes resource object.

HTTP Request

PATCH https://example.com/documents/{id}

URL-Parameter

Parameter Beschreibung
id die ID des Dokuments

HTTP Request Body

Im Request-Body muss das modifizierte Dokument als ein einziges resource object enthalten sein. Wenn Attribute oder Relationen ausgelassen werden, interpretiert der Server dies so, als ob sie mit ihren aktuellen Werten enthalten wären.

// Ein Beispiel:

POST /documents/17 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "documents",
    "id": "17",
    "attributes": {
      "name": "Der neue Name des Dokuments",
      "description": "Die neue Beschreibung des Dokuments"
    }
}

Authorisierung

Für das Ändern der Metadaten eines Dokuments gelten die für die Veranstaltung bzw. Einrichtungen gültigen Einschränkungen ganz genau wie in der üblichen Stud.IP-Weboberfläche.

Einen Ordner auslesen

curl --request GET \
    --url https://example.com/document-folders/{id} \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/document-folders/{id}', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "document-folders",
    "id": "106ca0f8cc1534f79770499fee2f2f91",
    "attributes": {
      "name": "Allgemeine Dateien",
      "description": "Allgemeine Beschreibung",
      "permission": "frwx",
      "mkdate": "2018-01-30T10:07:17+01:00",
      "chdate": "2018-01-30T10:07:17+01:00",
      "priority": 0
    },
    "relationships": {
      "documents": {
        "links": {
          "related": "https://example.com/document-folders/106ca0f8cc1534f79770499fee2f2f91/documents"
        }
      },
      "document-folders": {
        "links": {
          "related": "https://example.com/document-folders/106ca0f8cc1534f79770499fee2f2f91/document-folders"
        }
      },
      "owner": {
        "data": {
          "type": "users",
          "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
        },
        "links": {
          "related": "https://example.com/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
        }
      },
      "range": {
        "data": {
          "type": "courses",
          "id": "a07535cf2f8a72df33c12ddfa4b53dde"
        },
        "links": {
          "related": "https://example.com/courses/a07535cf2f8a72df33c12ddfa4b53dde"
        }
      }
    },
    "links": {
      "self": "https://example.com/document-folders/106ca0f8cc1534f79770499fee2f2f91"
    }
  }
}

HTTP Request

GET https://example.com/document-folders/{id}

URL-Parameter

Parameter Beschreibung
id die ID des Ordners

Authorisierung

Autoren sehen nur eingeschränkt Ordner in ihren Veranstaltungen (nach den üblichen Stud.IP-Regeln). Tutoren und Dozenten haben Zugriff auf alle Ordner ihrer Veranstaltung; Administratoren entsprechend auf Ordner, die zu Veranstaltungen ihrer Einrichtungen gehören; Root natürlich auf alle.

Alle Kindordner eines Ordners

curl --request GET \
    --url https://example.com/document-folders/{id}/document-folders \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/document-folders/{id}/document-folders', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 30,
      "total": 2
    }
  },
  "links": {
    "first": "/?page[offset]=0&page[limit]=30",
    "last": "/?page[offset]=0&page[limit]=30"
  },
  "data": [
    {
      "type": "document-folders",
      "id": "b819b13a4845547ed77db16f03969900",
      "attributes": {
        "name": "Kind 1",
        "description": null,
        "permission": "frwx",
        "mkdate": "2018-01-30T10:30:41+01:00",
        "chdate": "2018-01-30T10:30:41+01:00",
        "priority": 0
      },
      "relationships": {
        "documents": {
          "links": {
            "related": "https://example.com/document-folders/b819b13a4845547ed77db16f03969900/documents"
          }
        },
        "document-folders": {
          "links": {
            "related": "https://example.com/document-folders/b819b13a4845547ed77db16f03969900/document-folders"
          }
        },
        "owner": {
          "data": {
            "type": "users",
            "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
          },
          "links": {
            "related": "https://example.com/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
          }
        },
        "parent": {
          "data": {
            "type": "document-folders",
            "id": "9414828f7dd9c36975ac44e464f68d9c"
          },
          "links": {
            "related": "https://example.com/document-folders/9414828f7dd9c36975ac44e464f68d9c"
          }
        },
        "range": {
          "data": {
            "type": "courses",
            "id": "a07535cf2f8a72df33c12ddfa4b53dde"
          },
          "links": {
            "related": "https://example.com/courses/a07535cf2f8a72df33c12ddfa4b53dde"
          }
        }
      },
      "links": {
        "self": "https://example.com/document-folders/b819b13a4845547ed77db16f03969900"
      }
    },
    "[...]"
  ]
}

HTTP Request

GET https://example.com/document-folders/{id}/document-folders

URL-Parameter

Parameter Beschreibung
id die ID des Ordners

Authorisierung

Die Kindordner eines Ordners darf man nur sehen, wenn man den Ordner sehen würde. Außerdem greifen die Stud.IP-üblichen Beschränkungen: Hausaufgabenorder und Dateiberechtigungen werden entsprechend berücksichtigt.

Alle Dokumente eines Ordners

curl --request GET \
    --url https://example.com/document-folders/{id}/documents \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/document-folders/{id}/documents', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 30,
      "total": 2
    }
  },
  "links": {
    "first": "/?page[offset]=0&page[limit]=30",
    "last": "/?page[offset]=0&page[limit]=30"
  },
  "data": [
    {
      "type": "documents",
      "id": "1a7be00625cb1b71cdf113b3d4d42957",
      "attributes": {
        "name": "Dateiname1",
        "description": "Dateibeschreibung 1",
        "filename": "Dateiname1",
        "mkdate": "2018-01-30T10:35:54+01:00",
        "chdate": "2018-01-30T10:35:54+01:00",
        "filesize": 17,
        "downloads": 0,
        "priority": 0
      },
      "relationships": {
        "parent": {
          "data": {
            "type": "document-folders",
            "id": "8ed90d64dfdc754e6fd6cc5bdcbbc5c9"
          },
          "links": {
            "related": "https://example.com/document-folders/8ed90d64dfdc754e6fd6cc5bdcbbc5c9"
          }
        },
        "range": {
          "data": {
            "type": "courses",
            "id": "a07535cf2f8a72df33c12ddfa4b53dde"
          },
          "links": {
            "related": "https://example.com/courses/a07535cf2f8a72df33c12ddfa4b53dde"
          }
        },
        "owner": {
          "data": {
            "type": "users",
            "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
          },
          "links": {
            "related": "https://example.com/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
          }
        }
      },
      "links": {
        "self": "https://example.com/documents/1a7be00625cb1b71cdf113b3d4d42957"
      },
      "meta": {
        "download-url": "https://example.com/documents/1a7be00625cb1b71cdf113b3d4d42957/content"
      }
    },
    "[...]"
  ]
}

HTTP Request

GET https://example.com/document-folders/{id}/documents

URL-Parameter

Parameter Beschreibung
id die ID des Ordners

Authorisierung

Die Dokumente eines Ordners darf man nur sehen, wenn man den Ordner sehen würde. Außerdem greifen die Stud.IP-üblichen Beschränkungen: Hausaufgabenorder und Dateiberechtigungen werden entsprechend berücksichtigt.

Eine Lizenz auslesen

curl --request GET \
    --url https://example.com/document-licenses/{id} \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"
fetch('https://example.com/document-licenses/{id}', {
    method: 'GET',
    mode: 'cors',
    headers: new Headers({
        'Authorization': `Basic ${btoa('test_autor:testing')}`
    })
}).then(response => console.log(response))

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "document-licenses",
    "id": "2",
    "attributes": {
      "name": "Ungekl\u00c3\u00a4rte Lizenz",
      "description": "Bitte geben Sie an, welcher Lizenz das hochgeladene Material unterliegt bzw. auf welcher Grundlage Sie es zug\u00c3\u00a4nglich machen. Unterbleibt diese Angabe, wird beim Herunterladen auf den ungekl\u00c3\u00a4rten Lizenzstatus hingewiesen.",
      "student-description": "Diese Datei enth\u00c3\u00a4lt Material mit einer ungekl\u00c3\u00a4rten Lizenz. Zu Fragen der Nutzung und Weitergabe wenden Sie sich an die Person, die diese Datei hochgeladen hat.",
      "protected": 2
    },
    "links": {
      "self": "https://example.com/document-licenses/2"
    }
  }
}

HTTP Request

GET https://example.com/document-licenses/{id}

URL-Parameter

Parameter Beschreibung
id die ID der Lizenz

Authorisierung

Jeder kann Lizenzen auslesen.

TODO: Dokumente durchsuchen

Sucht in allen Veranstaltungen eines Nutzers nach passenden Dokumenten, auf die der API-Nutzer Zugriff hat.

GET /documents?filter[search]=

TODO: Alle Dokumente einer Veranstaltung/Einrichtung

GET /{type:courses|institutes}/{id}/relationships/documents

see http://jsonapi.org/format/#fetching-relationships

TODO: Neuen Unterordner anlegen

POST /document-folders/{id}/document-folders

TODO: Neuen Ordner in Veranstaltung/Einrichtung anlegen

POST /{type:courses|institutes}/{id}/document-folders

TODO: Ordner umbenennen

PATCH /document-folders/{id}

TODO: Ordner löschen

DELETE /document-folders/{id}

TODO: Alle Lizenzen auslesen

GET /document-licenses

Dateibereich v4.0+

In Stud.IP hat jeder Nutzer, jede Einrichtung und jede Veranstaltung einen eigenen Dateibereich. Dateibereiche sind (spezielle) Ordner. Ordner können Dateien und Ordner enthalten, in denen sich wiederum Dateien und Ordner befinden können.

Es gibt verschiedene Arten von Ordnern, die sich in der Regel darin unterscheiden, wer sie sehen kann und wer Lese- und/oder Schreibzugriff auf diese Ordner hat.

Schemata

Schema "file-refs"

Aus Nutzersicht sind Dateien in Stud.IP Ressourcen vom Typ "file-refs". Technisch gesehen sind es allerdings Verweise auf die Ressourcen vom Typ "files". Letztere sind die tatsächlich auf der Festplatte gespeicherten Dateien, die mithilfe der "file-refs" nur verlinkt werden.

Vereinfacht gesagt, hantiert man in der Regel immer mit "file-refs".

Attribute

Attribut Beschreibung
name der Name der Datei
description eine optionale Beschreibung der Datei
mkdate das Erstellungsdatum der Datei
chdate das Datum der letzten Änderung der Metadaten ('name', 'description', …) der Datei
downloads Wie häufig wurde diese Datei heruntergeladen?
filesize die Größe der Datei in Byte
storage TODO

Relationen

Relation Beschreibung
file die tatsächliche Datei auf der Festplatte
owner der Nutzer, dem diese Datei gehört
parent der Ordner, im dem diese Datei liegt
range die Veranstaltung, die Einrichtung oder der Nutzer, in dessen Dateibereich diese Datei liegt
terms-of-use die Lizenz, unter der diese Datei verfügbar gemacht wird

Meta

In den Metadaten von Dateien ist der "download-link" enthalten, um den Inhalt der Datei herunterzuladen.

Schema "files"

Anders als Ressourcen vom Typ "file-refs" sind Ressourcen vom Typ "files" über die grafische Oberfläche nicht verfügbar. Technisch werden "files" verwendet, um die Dateien tatsächlich auf der Festplatte (oder einem entfernten Speicherort) abzulegen.

Erst durch die Verknüpfung durch "file-refs" werden Ressourcen vom Typ "files" sichtbar.

Attribute

Attribut Beschreibung
name der Name der Datei
mime-type der MIME-Typ der Datei
size die Größe der Datei in Bytes
storage TODO
mkdate das Erstellungsdatum der Datei
chdate das Datum der letzten Änderung der Datei

Relationen

Relation Beschreibung
file-refs alle Ressourcen vom Typ "file-refs", die auf diese Datei verweisen
owner der Nutzer, dem diese Datei gehört

Type "folders"

Ressourcen vom Typ "folders" sind im herkömmlichen Sinne Ordner und können weitere "folders" oder Ressourcen vom Typ "file-refs" enthalten.

Es gibt verschiedene Arten von "folders". In Stud.IP werden aber vorrangig "StandardFolders" verwendet. Für diese sind alle Operationen möglich. Für andere Arten entscheiden die Implementierungen jeweils selbst, ob die Operation möglich ist.

Attribute

Attribut Beschreibung
folder-type die Art des Ordners
name der Name des Ordners
description die Beschreibung des Ordners
mkdate das Erstellungsdatum des Ordners
chdate das Datum der letzten Änderung des Ordners
is-visible Darf der eingeloggte Nutzer den Ordner sehen?
is-readable Darf der eingeloggte Nutzer den Ordner öffnen?
is-writable Darf der eingeloggte Nutzer im Ordner Dateien erstellen?
is-editable Darf der eingeloggte Nutzer den Ordner bearbeiten?
is-subfolder-allowed Darf der eingeloggte Nutzer im Ordner weitere Ordner erstellen?

Relationen

Relation Beschreibung
owner der Nutzer, dem dieser Ordner gehört
parent der Ordner, in dem sich dieser Ordner befindet
range die Veranstaltung, die Einrichtung oder der Nutzer, in dessen Dateibereich dieser Ordner liegt
folders die Ordner, die sich in diesem Ordner befinden
file-refs die Dateien, die sich in diesem Ordner befinden

Type "terms-of-use"

Jede Datei unterliegt einer Lizenz, die die Nutzung, Weitergabe und Veränderung regelt.

Attribute

Attribut Beschreibung
name der Name der Lizenz
description die Beschreibung der Lizenz
icon das für die Lizenz verwendete Icon
mkdate das Erstellungsdatum der Lizenz
chdate das Datum der letzten Änderung der Lizenz

Relationen

Lizenzen ('terms-of-use') haben keine Relationen.

Alle Lizenzen

curl --request GET \
    --url https://example.com/terms-of-use \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Diese Route erfragt alle im Stud.IP registrierten Lizenzen von Dateien.

HTTP Request

GET /terms-of-use

Autorisierung

Jeder Nutzer darf diese Route verwenden.

Eine Lizenz auslesen

curl --request GET \
    --url https://example.com/terms-of-use/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route kann eine beliebige Lizenz ausgelesen werden.

HTTP Request

GET /terms-of-use/{id}

Parameter Beschreibung
id die ID der Lizenz

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder Nutzer darf diese Route verwenden.

Alle Dateien eines Dateibereichs

curl --request GET \
    --url https://example.com/<courses,institutes,users>/<ID>/file-refs \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Der Request liefert JSON ähnlich wie dieses:

Mit dieser Route können alle Dateien eines Dateibereichs ausgelesen werden. Das Ergebnis ist eine flache Liste aller Dateien, ungeachtet der Zugehörigkeit zu Ordnern dieses Dateibereichs.

HTTP Request

GET /courses/{id}/file-refs GET /institutes/{id}/file-refs GET /users/{id}/file-refs

Parameter Beschreibung
id die ID der Veranstaltung, der Einrichtung oder des Nutzers

URL-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset (siehe Paginierung)
page[limit] 30 das Limit (siehe Paginierung)

Autorisierung

Die Dateien einer Einrichtung darf jeder Nutzer sehen. Die Dateien einer Veranstaltung sehen alle Nutzer, die Zugriff auf die Veranstaltung haben. Die Dateien eines Nutzers sehen alle, es sei denn der Nutzer ist unsichtbar.

Im Übrigen gelten die Zugriffsregeln der Ordner, in denen die Dateien liegen.

Alle Ordner eines Dateibereichs

curl --request GET \
    --url https://example.com/<courses,institutes,users>/<ID>/folders \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route können alle Ordner eines Dateibereichs ausgelesen werden. Das Ergebnis ist eine flache Liste aller Ordner, ungeachtet der Zugehörigkeit zu Ordnern dieses Dateibereichs.

HTTP Request

GET /courses/{id}/folders GET /institutes/{id}/folders GET /users/{id}/folders

Parameter Beschreibung
id die ID der Veranstaltung, der Einrichtung oder des Nutzers

URL-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset (siehe Paginierung)
page[limit] 30 das Limit (siehe Paginierung)

Autorisierung

Die Ordner einer Einrichtung darf jeder Nutzer sehen. Die Ordner einer Veranstaltung sehen alle Nutzer, die Zugriff auf die Veranstaltung haben. Die Ordner eines Nutzers sehen alle, es sei denn der Nutzer ist unsichtbar.

Im Übrigen gelten die Zugriffsregeln der Ordner, in denen die Ordner liegen.

Einen Ordner erstellen

Ein Ordner kann einfach über diese Route angelegt werden.

   curl --request POST \
       --url https://example.com/courses/<ID>/folders \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`" \
       --data '{"data": {"type": "folders","attributes": {"name": "Name of the folder"}, "relationships": {"parent": {"data": {"type":"folders","id":"<any-folder-id>"}}}}}'

HTTP Request

POST /courses/{id}/folders POST /institutes/{id}/folders POST /users/{id}/folders

Parameter Beschreibung
id die ID der Veranstaltung, der Einrichtung oder des Nutzers

Der Request-Body enthält ein "JSONAPI resource object" vom Typ "folders". Name und übergeordneter, enthaltender Ordner sind erforderlich: Das Attribut "name" und die Relation "parent", die auf ein "folders"-Objekt verweist, sind verpflichtend.

URL-Parameter

keine Parameter

Autorisierung

Ob ein Ordner angelegt werden darf, wird von der jeweiligen Implementation des Zielordners entschieden.

Eine Datei auslesen

curl --request GET \
    --url https://example.com/file-refs/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route kann eine Datei ausgelesen werden.

HTTP Request

GET /file-refs/{id}

Parameter Beschreibung
id die ID der Datei

URL-Parameter

keine Parameter

Autorisierung

Ob eine Datei ausgelesen werden darf, entscheidet der übergeordnete Ordner.

Metadaten einer Datei ändern

curl --request PATCH \
    --url https://example.com/file-refs/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --header "Content-Type: application/vnd.api+json" \
    --data '{"data": {"type": "file-refs","id":"<id-der-datei>", \
             "attributes":{"name":"neuer-name.jpg"}}}'

Mit dieser Route kann der Name, die Beschreibung und/oder die Lizenz einer Datei geändert werden. Dazu wird JSONAPI-typisch das angepasste "resource object" an diese Route geschickt.

HTTP Request

PATCH /file-refs/{id}

Parameter Beschreibung
id die ID der Datei

Der Request-Body enthält das veränderte "resource object".

URL-Parameter

keine URL-Parameter

Autorisierung

Ob eine Datei angepasst werden darf, entscheidet der übergeordnete Ordner.

Eine Datei löschen

curl --request DELETE \
    --url https://example.com/file-refs/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route löscht man eine Datei.

HTTP Request

DELETE /file-refs/{id}

Parameter Beschreibung
id die ID der Datei

URL-Parameter

keine URL-Parameter

Autorisierung

ob eine Datei gelöscht werden kann, entscheidet der übergeordnete Ordner.

Lizenz einer Datei auslesen

curl --request GET \
    --url https://example.com/file-refs/<ID>/relationships/terms-of-use \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Um die Relation einer Datei zu einer Lizenz auszulesen, verwendet man diese Route.

HTTP Request

GET /file-refs/<ID>/relationships/terms-of-use

Parameter Beschreibung
id die ID der Datei

URL-Parameter

keine URL-Parameter

Autorisierung

Der übergeordnete Ordner der Datei entscheidet.

Lizenz einer Datei ändern

curl --request PATCH \
    --url https://example.com/file-refs/<ID>/relationships/terms-of-use \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --header "Content-Type: application/vnd.api+json" \
    --data '{"data": {"type": "terms-of-use","id": "<id-der-lizenz>"}}'

Um die Relation einer Datei zu einer Lizenz zu ändern, verwendet man diese Route. Das Löschen der Relation zur Datei ist ausgeschlossen.

HTTP Request

PATCH /file-refs/<ID>/relationships/terms-of-use

Parameter Beschreibung
id die ID der Datei

Der Request-Body muss einen "resource identifier" von Typ "terms-of-use" enthalten.

URL-Parameter

keine URL-Parameter

Autorisierung

Der übergeordnete Ordner der Datei entscheidet.

Den ETag einer Datei auslesen

curl --request HEAD \
    --url https://example.com/file-refs/<ID>/content \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Um einen Fingerabdruck (ETag) des tatsächlichen Inhalts einer Datei zu bekommen, kann man diese nicht-JSON-API-Route aufrufen.

HTTP Request

HEAD /file-refs/{id}/content

Parameter Beschreibung
id die ID der Datei

URL-Parameter

keine URL-Parameter

Autorisierung

Der übergeordnete Ordner der Datei entscheidet.

Eine Datei herunterladen

curl --request GET \
    --url https://example.com/file-refs/<ID>/content \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route kann der Inhalt einer Datei heruntergeladen werden.

HTTP Request

GET /file-refs/{id}/content

Parameter Beschreibung
id die ID der Datei

Der Request kann einen ETag-Header mitbringen, um redundante Datenübertragung zu vermeiden.

URL-Parameter

keine URL-Parameter

Autorisierung

Der übergeordnete Ordner der Datei entscheidet.

Inhalt einer Datei aktualisieren

curl --request POST --url https://example.com/file-refs/<ID>/content \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    -F 'myfile=@/path/to/local/file'

Mit dieser Route kann der Inhalt einer vorhandenen Datei überschrieben werden. Dazu wird eine einzige Datei "multipart/form-data"-kodiert an diese Route geschickt.

HTTP Request

POST /file-refs/{id}/content

Im Request-Body muss dann eine Datei "multipart/form-data"-kodiert enthalten sein.

URL-Parameter

keine URL-Parameter

Autorisierung

Der übergeordnete Ordner der Datei entscheidet.

Einen Ordner auslesen

curl --request GET \
    --url https://example.com/folders/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route kann man die Daten eines Ordners auslesen.

HTTP Request

GET /folders/{id}

Parameter Beschreibung
id die ID des Ordners

URL-Parameter

keine URL-Parameter

Autorisierung

Die Art des Ordners entscheidet über die Autorisierung.

Einen Ordner ändern

curl --request PATCH \
    --url https://example.com/folders/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --header "Content-Type: application/vnd.api+json" \
    --data '{"data": {"type":"folders","id":"<id-der-lizenz>", \
             "attributes":{"name":"Neuer Name"}}}'

Mit dieser Route kann der Name und/oder die Beschreibung geändert werden. Außerdem kann man den Ordner in einen anderen Ordner verschieben. Dazu ändert man die "parent"-Relation.

HTTP Request

PATCH /folders/{id}

Parameter Beschreibung
id die ID des Ordners

URL-Parameter

keine URL-Parameter

Autorisierung

Die Art des Ordners entscheidet über die Autorisierung.

Einen Ordner löschen

curl --request DELETE \
    --url https://example.com/folders/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route kann man einen Ordner löschen.

HTTP Request

DELETE /folders/{id}

Parameter Beschreibung
id die ID des Ordners

URL-Parameter

keine URL-Parameter

Autorisierung

Die Art des Ordners entscheidet über die Autorisierung.

Alle Dateien eines Ordners

curl --request GET \
    --url https://example.com/folders/<ID>/file-refs \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route erhält man eine Liste aller Dateien, die direkt in einem Ordner liegen.

HTTP Request

GET /folders/{id}/file-refs

Parameter Beschreibung
id die ID des Ordners

URL-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset (siehe Paginierung)
page[limit] 30 das Limit (siehe Paginierung)

Autorisierung

Ob man die Liste der Dateien eines Ordners sehen darf, entscheidet die Implementierung des Ordners.

Alle Ordner eines Ordners

curl --request GET \
    --url https://example.com/folders/<ID>/folders \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route erhält man eine Liste aller Ordner, die direkt in einem Ordner liegen.

HTTP Request

GET /folders/{id}/folders

Parameter Beschreibung
id die ID des Ordners

URL-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset (siehe Paginierung)
page[limit] 30 das Limit (siehe Paginierung)

Autorisierung

Ob man die Liste der Ordner eines Ordners sehen darf, entscheidet die Implementierung des Ordners.

Eine Datei erstellen

Eine Datei wird immer in einem Ordner erstellt. Da Dateien aus Metadaten und Inhalt bestehen, muss das Erstellen einer Datei in zwei Schritten passieren. Dazu kann entweder

Variante a.

curl --request POST --url "https://example.com/folders/<ID>/file-refs" \
     -F 'file=@/pfad/zu/einer-neuen-datei.jpg' \
     --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`"

Zuerst sendet man einen POST-Request mit Content-Type: multipart/form-data und der Datei im Request-Body an die angegebene URL.

Man erhält im Erfolgsfall einen Status-Code 201 und einen Location-Header, der einen zum neu erstellten Dokument in die JSON:API bringt.

Der Dateiname wird standardmäßig aus dem Upload genommen und auch für den Namen der Datei verwendet.

Will man einen anderen Dateinamen verwenden, kann man einen HTTP-Header verwenden: Slug: neuer-dateiname.txt.

Über die URL aus dem erhaltenen Location-Header erhält man die JSON:API-Repräsentation der hochgeladenen Datei.

Nun können mit einem (JSON:API-typischen) PATCH-Request an diese Route Modifikationen an den Metadaten (wie Beschreibung usw.) vorgenommen werden.

Variante b.

curl --request POST --url https://example.com/folders/<ID>/file-refs \
    --header "Content-Type: application/vnd.api+json" \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --data '{"data": { "type": "file-refs", "attributes": { "name": "iason.txt", "description": "Iasons Lebenslauf"}, "relationships":{"terms-of-use": {"data": {"type": "terms-of-use", "id": "FREE_LICENSE"}}}}}'

Zunächst sendet man einen POST-Request mit Content-Type: application/vnd.api+json an die URL.

Im Request-Body muss dann eine JSON:API-typische Repräsentation der neuen Datei enthalten sein. Im Erfolgsfall erhält man dann eine Repräsentation der neu angelegten Datei, die aber derzeit noch keinen Inhalt hat.

Daher muss der Inhalt in einem zweiten Request hochgeladen werden. Dazu wird – wie unter "Inhalt einer Datei aktualisieren" beschrieben – ein POST-Request an die download-url geschickt.

HTTP Request

POST /folders/{id}/file-refs

Im Request-Body befindet sich dann entweder eine "multipart/form-data"-kodierte Datei oder ein JSON-API-spezifisches "resource object".

Wenn man ein JSON-API-"resource object" verschickt, muss die Relation terms-of-use (die Lizenz) enthalten sein. Ohne Lizenz können keine Dateien angelegt werden.

URL-Parameter

Parameter Beschreibung
id die ID des Ordners

Authorisierung

Ob man eine Datei erstellen darf, entscheidet die Implementierung des Ordners.

Eine Datei kopieren

Um eine Datei zu kopieren, verwendet man die "Variante b." für das Anlegen von Dateien.

Zuerst benötigt man den "resource identifier" der Relation file der zu kopierenden Datei. Dann schickt man ein JSON-API-"resource object" an die URL zum Erstellen einer Datei und setzt dort diesen "resource identifier" als Relation file der neuen Datei.

Wenn man selbst der Besitzer der Quelldatei ist, bleibt der Verweis auf das file bestehen. Ist man nicht der Besitzer der Quelldatei, wird auch das file kopiert und man selbst dessen Besitzer.

Einen Ordner kopieren

curl -F "destination=<destination-ID>" \
     --url "https://example.com/folders/<source-ID>/copy" \
     --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`"

Um einen Ordner zu kopieren, wird diese Route verwendet, die allerdings nicht JSON-API-konform ist. Dazu wird ein POST-Request an die Route des Ordners geschickt, in deren Request-Body der Zielordner spezifiziert wird. Der Request-Body muss vom "multipart/form-data"-kodiert sein.

HTTP Request

POST /folders/{id}/copy

Der "Content-Type" des Requests muss "multipart/form-data" sein. Im Request-Body muss unter dem Schlüssel "destination" die ID des Zielordners enthalten.

Wenn der Request erfolgreich war, bekommt man einen Status-Code 201 und einen Location-Header, der auf den neuen, kopierten Ordner zeigt.

Authorisierung

Jeder Nutzer, der den Quellordner öffnen und im Zielordner schreiben darf, kann diese Route aufrufen.

Einen Ordner erstellen

curl --request POST \
    --url https://example.com/folders/<ID>/folders \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --data '{"data": { "type": "folders", "attributes": {"name":"Neuer Ordner"}}}'

Mit dieser Route kann man einen neuen Ordner anlegen.

HTTP Request

POST /folders/{id}/folders

Parameter Beschreibung
id die ID des übergeordneten Ordners

URL-Parameter

keine URL-Parameter

Autorisierung

Ob man einen Ordner erstellen darf, entscheidet die Implementierung des übergeordneten Ordners.

Ein "File" auslesen

curl --request GET \
    --url https://example.com/files/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Die Dateien, die in den obigen Routen genannt werden, sind technisch gesehen nur Verweise auf tatsächliche Dateien auf der Festplatte o.ä. Auch die tatsächlichen Dateien ("files") können ausgelesen werden. Dazu verwendet man diese Route.

HTTP Request

GET /files/{id}

Parameter Beschreibung
id die ID des "files"

URL-Parameter

keine URL-Parameter

Autorisierung

Ein "file" kann ein Nutzer dann sehen, wenn eine der darauf verweisenden Dateien vom Nutzer gesehen werden kann.

Alle Dateien eines "Files"

curl --request GET \
    --url https://example.com/files/<ID>/file-refs \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route können alle Dateien, die auf dieses "file" verweisen, ausgelesen werden.

HTTP Request

GET /files/{id}/file-refs

Parameter Beschreibung
id die ID des "files"

URL-Parameter

keine URL-Parameter

Autorisierung

Die Route kann sinnvoll aufgerufen werden, wenn man eine der darauf verweisenden Dateien sehen kann.

Alle Datei-IDs eines "Files"

curl --request GET \
    --url https://example.com/files/<ID>/relationships/file-refs \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Diese Route wird verwendet, um alle IDs der Dateien zu erhalten, die auf dieses "file" verweisen.

HTTP Request

GET /files/{id}/relationships/file-refs

Parameter Beschreibung
id die ID des "files"

URL-Parameter

keine URL-Parameter

Autorisierung

Die Route kann sinnvoll aufgerufen werden, wenn man eine der auf das "file" verweisenden Dateien sehen kann.

Forum

Das Stud.IP-Forum bietet die Möglichkeit Beiträge zu erstellen, zu kommentieren und zu Kategorisieren. Jedes Forum ist an genau eine Veranstaltung gebunden. Die Schema's werden in Forum-Categories und Forum-Entries unterteilt.

Schema "forum-categories"

Kategorien für Einträge haben einen Namen und geben die Hierarchie des Forums anhand ihrer Position an.

Attribute

Attribut Beschreibung
title Name einer Kategorie
position Position einer Kategorie

Relationen

Relation Beschreibung
course Der Kurs des Forums, indem die Kategorie angelegt ist
entries Alle Forum-Einträge einer Forum-Kategorie

Schema "forum-entries"

Einträge des Forums liegen auf verschiedenen Ebenen. Sie können direkt in Kategorien als Themen erstellt werden oder an vorhandene Einträge angebunden werden.

Attribute

Attribut Beschreibung
title Name eines Entries (sollte nur bei Themen angezeigt werden)
content Gibt den Inhalt eines Entries wieder
area Dieses Attribut wird mitgeführt (ist aber idr. '0')

Relationen

Relation Beschreibung
category Die Forum-Kategorie des Forumeintrags
entries Alle Untereinträge eines Forumeintrags

Alle Forum-Kategorien eines Kurses auslesen

GET /courses/{id}/forum-categories

Parameter Beschreibung
id Die ID des Kurses
   curl --request GET \
       --url https://example.com/courses/<COURSE-ID>/forum-categories \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
       --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": [
    {
      "type": "forum-categories",
      "id": "d6b887a73f024cf31b4a01f41531b809",
      "attributes": {
        "title": "NewStuff",
        "position": 0
      },
      "relationships": {
        "course": {
          "data": {
            "type": "courses",
            "id": "1b7d3834e42c1569947e0eab7b63ed19"
          },
          "links": {
            "related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
          }
        }
      },
      "links": {
        "self": "/stud35/plugins.php/argonautsplugin/forum-categories/d6b887a73f024cf31b4a01f41531b809"
      }
    },
    {
      "type": "forum-categories",
      "id": "3710de2efd59869ab7ed7e410f70947f",
      "attributes": {
        "title": "CatCreateRoute",
        "position": 1
      },
      "relationships": {
        "course": {
          "data": {
            "type": "courses",
            "id": "1b7d3834e42c1569947e0eab7b63ed19"
          },
          "links": {
            "related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
          }
        }
      },
      "links": {
        "self": "/stud35/plugins.php/argonautsplugin/forum-categories/3710de2efd59869ab7ed7e410f70947f"
      }
    },
    {
      "type": "forum-categories",
      "id": "7684942d4a1d3f8ab0752165e22c31a6",
      "attributes": {
        "title": "TESTECASE ",
        "position": 2
      },
      "relationships": {
        "course": {
          "data": {
            "type": "courses",
            "id": "1b7d3834e42c1569947e0eab7b63ed19"
          },
          "links": {
            "related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
          }
        }
      },
      "links": {
        "self": "/stud35/plugins.php/argonautsplugin/forum-categories/7684942d4a1d3f8ab0752165e22c31a6"
      }
    },
    {
      "type": "forum-categories",
      "id": "4ca16225a42c94957c4129da5f0bef2d",
      "attributes": {
        "title": "CatCreateRoute",
        "position": 3
      },
      "relationships": {
        "course": {
          "data": {
            "type": "courses",
            "id": "1b7d3834e42c1569947e0eab7b63ed19"
          },
          "links": {
            "related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
          }
        }
      },
      "links": {
        "self": "/stud35/plugins.php/argonautsplugin/forum-categories/4ca16225a42c94957c4129da5f0bef2d"
      }
    },
    {
      "type": "forum-categories",
      "id": "1b7d3834e42c1569947e0eab7b63ed19",
      "attributes": {
        "title": "Allgemein",
        "position": 4
      },
      "relationships": {
        "course": {
          "data": {
            "type": "courses",
            "id": "1b7d3834e42c1569947e0eab7b63ed19"
          },
          "links": {
            "related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
          }
        }
      },
      "links": {
        "self": "/stud35/plugins.php/argonautsplugin/forum-categories/1b7d3834e42c1569947e0eab7b63ed19"
      }
    }
  ]
}

Eine Forum-Kategorie auslesen

GET /forum-categories/{id}

Parameter Beschreibung
id Die ID der Kategorie
   curl --request GET \
       --url https://example.com/forum-categories/<FORUM-CATEGORY-ID> \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
       --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
"data": {
"type": "forum-categories",
"id": "1b7d3834e42c1569947e0eab7b63ed19",
"attributes": {
"title": "Allgemein",
"position": 4
},
"relationships": {
"course": {
"data": {
"type": "courses",
"id": "1b7d3834e42c1569947e0eab7b63ed19"
},
"links": {
"related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
}
}
},
"links": {
"self": "/stud35/plugins.php/argonautsplugin/forum-categories/1b7d3834e42c1569947e0eab7b63ed19"
}
}
}

Einen Forum-Eintrag auslesen

GET /forum-entries/{id}

Parameter Beschreibung
id Die ID des Entries
  curl --request GET \
      --url https://example.com/forum-entries/<FORUM-ENTRY-ID> \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "forum-entries",
    "id": "1b7d3834e42c1569947e0eab7b63ed19",
    "attributes": {
      "title": "Übersicht",
      "area": 0,
      "content": ""
    },
    "relationships": {
      "category": {
        "data": {
          "type": "forum-categories",
          "id": null
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-categories/"
        }
      },
      "child-entries": {
        "data": [
          {
            "type": "forum-entries",
            "id": "2e6ff68d79c5e3f3ed24bd0274865e42"
          },
          {
            "type": "forum-entries",
            "id": "3e0ec8e69afe2502763730e17954d340"
          },
          {
            "type": "forum-entries",
            "id": "783e1b783a76f109eeb5fc19c43c2d08"
          },
          {
            "type": "forum-entries",
            "id": "9af47a2c1463b12a35e3a7c3a10bd53c"
          },
          {
            "type": "forum-entries",
            "id": "a5e119fc5b8cfc549ab9cc985e8609a1"
          },
          {
            "type": "forum-entries",
            "id": "b21ca75f9562d3a5751babaac49bbc9a"
          },
          {
            "type": "forum-entries",
            "id": "c2e21dfa7d071fb6f40ed29271f926aa"
          },
          {
            "type": "forum-entries",
            "id": "f5f8ea3da6fd945eb92dd0d1e1193132"
          }
        ],
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19/child-entries"
        }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19"
    }
  }
}

Alle Forum-Einträge einer Kategorie auslesen

GET /forum-categories/{id}/entries

Parameter Beschreibung
id Die ID der Kategorie
  curl --request GET \
      --url https://example.com/forum-categories/<CATEGORY-ID>/entries \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "forum-entries",
    "id": "1b7d3834e42c1569947e0eab7b63ed19",
    "attributes": {
      "title": "Übersicht",
      "area": 0,
      "content": ""
    },
    "relationships": {
      "category": {
        "data": {
          "type": "forum-categories",
          "id": null
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-categories/"
        }
      },
      "child-entries": {
        "data": [
          {
            "type": "forum-entries",
            "id": "2e6ff68d79c5e3f3ed24bd0274865e42"
          },
          {
            "type": "forum-entries",
            "id": "3e0ec8e69afe2502763730e17954d340"
          },
          {
            "type": "forum-entries",
            "id": "783e1b783a76f109eeb5fc19c43c2d08"
          },
          {
            "type": "forum-entries",
            "id": "9af47a2c1463b12a35e3a7c3a10bd53c"
          },
          {
            "type": "forum-entries",
            "id": "a5e119fc5b8cfc549ab9cc985e8609a1"
          },
          {
            "type": "forum-entries",
            "id": "b21ca75f9562d3a5751babaac49bbc9a"
          },
          {
            "type": "forum-entries",
            "id": "c2e21dfa7d071fb6f40ed29271f926aa"
          },
          {
            "type": "forum-entries",
            "id": "f5f8ea3da6fd945eb92dd0d1e1193132"
          }
        ],
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19/child-entries"
        }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19"
    }
  }
}

Alle Untereinträge eines Forumeintrags auslesen

GET /forum-entries/{id}/entries

Parameter Beschreibung
id Die ID des Eintrags
  curl --request GET \
      --url https://example.com/forum-entries/<FORUM-ENTRY-ID>/entries \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "forum-entries",
    "id": "1b7d3834e42c1569947e0eab7b63ed19",
    "attributes": {
      "title": "Übersicht",
      "area": 0,
      "content": ""
    },
    "relationships": {
      "category": {
        "data": {
          "type": "forum-categories",
          "id": null
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-categories/"
        }
      },
      "child-entries": {
        "data": [
          {
            "type": "forum-entries",
            "id": "2e6ff68d79c5e3f3ed24bd0274865e42"
          },
          {
            "type": "forum-entries",
            "id": "3e0ec8e69afe2502763730e17954d340"
          },
          {
            "type": "forum-entries",
            "id": "783e1b783a76f109eeb5fc19c43c2d08"
          },
          {
            "type": "forum-entries",
            "id": "9af47a2c1463b12a35e3a7c3a10bd53c"
          },
          {
            "type": "forum-entries",
            "id": "a5e119fc5b8cfc549ab9cc985e8609a1"
          },
          {
            "type": "forum-entries",
            "id": "b21ca75f9562d3a5751babaac49bbc9a"
          },
          {
            "type": "forum-entries",
            "id": "c2e21dfa7d071fb6f40ed29271f926aa"
          },
          {
            "type": "forum-entries",
            "id": "f5f8ea3da6fd945eb92dd0d1e1193132"
          }
        ],
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19/child-entries"
        }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19"
    }
  }
}

__

Eine Kategorie innerhalb eines Kurses anlegen

POST /courses/{id}/forum-categories

Parameter Beschreibung
id Die ID des Kurses
  curl --request POST \
      --url https://example.com/courses/<COURSE-ID>/categories \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data
      '{"data": {"type": "forum-categories","attributes": {"title": "CreateCategoryTest","content": "works"}
  }
}'

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
"data": {
"type": "forum-categories",
"id": "1b7d3834e42c1569947e0eab7b63ed19",
"attributes": {
"title": "Allgemein",
"position": 4
},
"relationships": {
"course": {
"data": {
"type": "courses",
"id": "1b7d3834e42c1569947e0eab7b63ed19"
},
"links": {
"related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
}
}
},
"links": {
"self": "/stud35/plugins.php/argonautsplugin/forum-categories/1b7d3834e42c1569947e0eab7b63ed19"
}
}
}

Einen Eintrag in eine Kategorie posten

POST /forum-categories/{id}/entries

Parameter Beschreibung
id Die ID der Kategorie
  curl --request POST \
      --url https://example.com/forum-entries/<FORUM-CATEGORY-ID>/entries \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data
      '{"data": {"type": "forum-entries","attributes": {"title": "TestTheRoute","content": "works!"}}}'

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "forum-entries",
    "id": "1b7d3834e42c1569947e0eab7b63ed19",
    "attributes": {
      "title": "Übersicht",
      "area": 0,
      "content": ""
    },
    "relationships": {
      "category": {
        "data": {
          "type": "forum-categories",
          "id": null
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-categories/"
        }
      },
      "child-entries": {
        "data": [
          {
            "type": "forum-entries",
            "id": "2e6ff68d79c5e3f3ed24bd0274865e42"
          },
          {
            "type": "forum-entries",
            "id": "3e0ec8e69afe2502763730e17954d340"
          },
          {
            "type": "forum-entries",
            "id": "783e1b783a76f109eeb5fc19c43c2d08"
          },
          {
            "type": "forum-entries",
            "id": "9af47a2c1463b12a35e3a7c3a10bd53c"
          },
          {
            "type": "forum-entries",
            "id": "a5e119fc5b8cfc549ab9cc985e8609a1"
          },
          {
            "type": "forum-entries",
            "id": "b21ca75f9562d3a5751babaac49bbc9a"
          },
          {
            "type": "forum-entries",
            "id": "c2e21dfa7d071fb6f40ed29271f926aa"
          },
          {
            "type": "forum-entries",
            "id": "f5f8ea3da6fd945eb92dd0d1e1193132"
          }
        ],
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19/child-entries"
        }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19"
    }
  }
}

Einen Eintrag unter einen Eintrag posten

POST /forum-entries/{id}/entries

Parameter Beschreibung
id Die ID des Eintrags
  curl --request POST \
      --url https://example.com/forum-entries/<FORUM-ENTRY-ID>/entries \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data
      '{"data": {"type": "forum-entries","attributes": {"title": "TestTheRoute","content": "works!"}}}'

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "forum-entries",
    "id": "1b7d3834e42c1569947e0eab7b63ed19",
    "attributes": {
      "title": "Übersicht",
      "area": 0,
      "content": ""
    },
    "relationships": {
      "category": {
        "data": {
          "type": "forum-categories",
          "id": null
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-categories/"
        }
      },
      "child-entries": {
        "data": [
          {
            "type": "forum-entries",
            "id": "2e6ff68d79c5e3f3ed24bd0274865e42"
          },
          {
            "type": "forum-entries",
            "id": "3e0ec8e69afe2502763730e17954d340"
          },
          {
            "type": "forum-entries",
            "id": "783e1b783a76f109eeb5fc19c43c2d08"
          },
          {
            "type": "forum-entries",
            "id": "9af47a2c1463b12a35e3a7c3a10bd53c"
          },
          {
            "type": "forum-entries",
            "id": "a5e119fc5b8cfc549ab9cc985e8609a1"
          },
          {
            "type": "forum-entries",
            "id": "b21ca75f9562d3a5751babaac49bbc9a"
          },
          {
            "type": "forum-entries",
            "id": "c2e21dfa7d071fb6f40ed29271f926aa"
          },
          {
            "type": "forum-entries",
            "id": "f5f8ea3da6fd945eb92dd0d1e1193132"
          }
        ],
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19/child-entries"
        }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/forum-entries/1b7d3834e42c1569947e0eab7b63ed19"
    }
  }
}

Einen Kategorie aktualisieren

PATCH /forum-categories/{id}

Parameter Beschreibung
id Die ID der Kategorie
  curl --request PATCH \
      --url https://example.com/forum-categories/<FORUM-CATEGORY-ID> \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data
      '{"data": {"type": "forum-categories","attributes": {"title": "UpdateCategory","content": "time for a change"}

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein. Der Nutzer sollte die entsprechenden Adminrechte verfügen oder Ersteller der Kategorie sein

Der Request liefert JSON ähnlich wie dieses:

{
"data": {
"type": "forum-categories",
"id": "1b7d3834e42c1569947e0eab7b63ed19",
"attributes": {
"title": "Allgemein",
"position": 4
},
"relationships": {
"course": {
"data": {
"type": "courses",
"id": "1b7d3834e42c1569947e0eab7b63ed19"
},
"links": {
"related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
}
}
},
"links": {
"self": "/stud35/plugins.php/argonautsplugin/forum-categories/1b7d3834e42c1569947e0eab7b63ed19"
}
}
}

Einen Forum-Eintrag aktualisieren

PATCH /forum-entries/{id}

Parameter Beschreibung
id Die ID des Eintrags
  curl --request PATCH \
      --url https://example.com/forum-entries/<FORUM-ENTRY-ID> \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data
      '{"data": {"type": "forum-entries","attributes": {"title": "Update an entry","content": "time for a change"}}}'

### Autorisierung Der Nutzer sollte Mitglied des entsprechenden Kurses sein. Der Nutzer sollte die entsprechenden Adminrechte verfügen oder Ersteller des Eintrags sein

Der Request liefert JSON ähnlich wie dieses:

{
"data": {
"type": "forum-categories",
"id": "1b7d3834e42c1569947e0eab7b63ed19",
"attributes": {
"title": "Allgemein",
"position": 4
},
"relationships": {
"course": {
"data": {
"type": "courses",
"id": "1b7d3834e42c1569947e0eab7b63ed19"
},
"links": {
"related": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19"
}
}
},
"links": {
"self": "/stud35/plugins.php/argonautsplugin/forum-categories/1b7d3834e42c1569947e0eab7b63ed19"
}
}
}

Eine Forum-Kategorie entfernen

DELETE /forum-categories/{id}

Parameter Beschreibung
id Die ID der Kategorie
  curl --request DELETE \
    --url https://example.com/forum-categories/<FORUM-CATEGORY-ID> \
    --header "Content-Type: application/vnd.api+json" \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein. Der Nutzer sollte die entsprechenden Adminrechte verfügen oder Ersteller der Kategorie sein.

Einen Forum-Eintrag entfernen

DELETE /forum-categories/{id}

Parameter Beschreibung
id Die ID des Eintrags
curl --request DELETE \
    --url https://example.com/forum-entries/<FORUM-ENTRY-ID> \
    --header "Content-Type: application/vnd.api+json" \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein. Der Nutzer sollte die entsprechenden Adminrechte verfügen oder Ersteller des Eintrags sein.

Einrichtungen

Die Einrichtungen der Stud.IP-Installation können mit den folgenden Routen abgefragt werden.

Schema 'institutes'

Alle Einrichtungen werden in Stud.IP mit diesem Schema abgebildet. Die id entspricht der in Stud.IP verwendeten Institut_id. Der Typ ist institutes.

Attribute

Attribut Beschreibung
name der Einrichtungsname
city die Stadt in der die Einrichtung liegt
street die Anschrift (Straße) der Einrichtung
phone die Telefonnummer der Einrichtung
fax die Faxnummer der Einrichtung
url die URL der Webseite der Einrichtung
mkdate das Erstellungsdatum der Einrichtung in Stud.IP
chdate das letztes Änderungsdatum der Einrichtungsdaten in Stud.IP

Relationen

keine Relationen

Schema 'institute-memberships'

Die Mitgliedschaft in einer Einrichtung wird in Stud.IP mit diesem Schema abgebildet.

Attribute

Attribut Beschreibung
permission die Rolle des Nutzers in der Einrichtung
office-hours die Sprechzeiten des Nutzers bzgl. der Einrichtung
location der Raum/Ort des Nutzers bzgl. der Einrichtung
phone die Telefonnummer des Nutzers bzgl. der Einrichtung
fax die Faxnummer des Nutzers bzgl. der Einrichtung

Relationen

Relation Beschreibung
institute die Einrichtung dieser Mitgliedschaft
user der Nutzer dieser Mitgliedschaft

Alle Einrichtungen

Dieser Endpoint liefert alle Einrichtungen im Stud.IP, die der JSON:API-Nutzer mit seinen credentials auch im Stud.IP selbst sehen darf. Die Ausgabe erfolgt paginiert und kann durch Angabe von Offset und Limit weitergeblättert werden.

HTTP Request

GET /institutes

   curl --request GET \
       --url https://example.com/institutes \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

URL-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset
page[limit] 30 das Limit

Authorisierung

Jeder Nutzer darf diese Route verwenden.

Eine Einrichtung

   curl --request GET \
       --url https://example.com/institutes/<INSTITUTE-ID> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Eine bestimmte Einrichtung kann einfach über diese Route ausgelesen werden.

HTTP Request

GET /institutes/{id}

Parameter Beschreibung
id Die ID des Instituts

URL-Parameter

keine URL-Parameter

Authorisierung

Jeder Nutzer darf diese Route verwenden.

Eine Mitgliedschaft

   curl --request GET \
       --url https://example.com/institute-memberships/<ID> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Mit dieser Route kann man eine Mitgliedschaft in einer Einrichtung auslesen.

HTTP Request

GET /institute-memberships/{id}

Parameter Beschreibung
id Die ID der Mitgliedschaft

URL-Parameter

keine URL-Parameter

Authorisierung

Mitgliedschaften können nur vom Nutzer selbst ausgelesen werden.

Kontakte

Nutzer können in Stud.IP sich andere Nutzer als Kontakte merken. Dafür ist kein neuer Ressourcentyp nötig.

Alle Kontakte

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

Mit dieser Route können alle Kontakte eines Nutzers ausgelesen werden.

HTTP Request

GET /users/{id}/contacts

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder Nutzer kann seine eigenen Kontakte sehen.

Alle Kontakt-IDs eines Nutzer

curl --request GET \
    --url https://example.com/users/<ID>/relationships/contacts \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route können alle IDs der Kontakte eines Nutzers ausgelesen werden.

(siehe http://jsonapi.org/format/#fetching-relationships)

HTTP Request

GET /users/{id}/relationships/contacts

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder Nutzer kann seine eigenen Kontakte sehen.

Kontakte eines Nutzers setzen

curl --request PATCH \
    --url https://example.com/users/<ID>/relationships/contacts \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --header "Content-Type: application/vnd.api+json" \
    --data '{"data": [ \
        {"type": "users","id":"<id1>"}, \
        {"type": "users","id":"<id2>"}, \
        {"type": "users","id":"<id3>"} \
        ]}'

Mit dieser Route kann man die alle Kontakte eines Nutzers setzen.

(siehe http://jsonapi.org/format/#crud-updating-to-many-relationships)

HTTP Request

PATCH /users/{id}/relationships/contacts

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder Nutzer kann seine eigenen Kontakte setzen.

Kontakte eines Nutzers hinzufügen

curl --request POST \
    --url https://example.com/users/<ID>/relationships/contacts \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --header "Content-Type: application/vnd.api+json" \
    --data '{"data": [ \
        {"type": "users","id":"<id4>"} \
        ]}'

Mit dieser Route kann man Kontakte eines Nutzers hinzufügen.

(siehe http://jsonapi.org/format/#crud-updating-to-many-relationships)

HTTP Request

POST /users/{id}/relationships/contacts

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder Nutzer kann seine eigenen Kontakte setzen.

Kontakte eines Nutzers löschen

curl --request DELETE \
    --url https://example.com/users/<ID>/relationships/contacts \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
    --header "Content-Type: application/vnd.api+json" \
    --data '{"data": [ \
        {"type": "users","id":"<id1>"}, \
        {"type": "users","id":"<id4>"} \
        ]}'

Mit dieser Route kann man Kontakte eines Nutzers löschen.

(siehe http://jsonapi.org/format/#crud-updating-to-many-relationships)

HTTP Request

DELETE /users/{id}/relationships/contacts

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder Nutzer kann seine eigenen Kontakte löschen.

Nachrichten

Schema "messages"

Die Bestandteile einer Nachricht sind mit denen einer typischen Mail gleichzusetzen.

Attribute

Attribut Beschreibung
subject Der Betreff einer Nachricht
message Der Content einer Nachricht
mkdate Erstellungsdatum einer Nachricht
priority Art der Relevanz
tags Themen der Nachricht

Relationen

Relation Beschreibung
sender Absendender Nutzer
recipients Emfpänger einer Nachricht

Alle Inbox-Nachrichten

Gibt alle Nachrichten eines Nutzers zurück.

HTTP Request

GET /users/{id}/inbox

Parameter

Parameter Beschreibung
id ID des Nutzers

URL-Parameter

Parameter Beschreibung
filter[unread] Sollen nur ungelesene Nachrichten ausgeliefert werden?

Wenn "filter[unread]" nicht gesetzt ist, werden alle Nachrichten ausgeliefert. Mit "filter[unread]=1" werden nur ungelesene Nachrichten zurück gegeben.

Authorisierung

Diese Route kann nur vom Besitzer der betreffenden Nachrichten genutzt werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/users/<user-id>/inbox \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Alle Outbox-Nachrichten

Gibt alle Outbox-Nachrichten eines Nutzers zurück

HTTP Request

GET /users/{id}/outbox

Parameter

Parameter Beschreibung
id ID des Nutzers

Authorisierung

Diese Route kann nur vom Besitzer der betreffenden Nachrichten genutzt werden.

   curl --request GET \
       --url https://example.com/blubber-postings/<posting-id>/users/<user-id>/outbox \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Eine Nachricht senden

HTTP Request

POST /messages

Authorisierung

Diese Route kann von jedem Studip-Nutzer genutzt werden.

Parameter

Diese Route benötigt keine Parameter

   curl --request POST \
       --url https://example.com/messages \
       --header "Content-Type: application/vnd.api+json" \
       --header "Authorization: Basic `echo -ne "root@studip:testing" | base64`" \
       --data
       '{"data": {"type": "messages","attributes": {"subject": "Eine neue E-Mail","message": "Das ist meine erste Mail - Dank der API super einfach.", "priority": "normal" }, "relationships": {"recipients": {"data": [{"type": "users","id": "6235c46eb9e962866ebdceece739ace5"}]}}}}'

Eine Nachricht ansehen

HTTP Request

GET /messages/{id}

Parameter Beschreibung
id ID der Nachricht

Authorisierung

Diese Route kann von Besitzern der jeweiligen Nachricht genutzt werden.

   curl --request GET \
       --url https://example.com/blubber-postings/messages/<message-id>/ \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Eine Nachricht löschen

Löscht eine Nachrichten

HTTP Request

DELETE /messages/{id}

Authorisierung

Diese Route kann von Besitzern der jeweiligen Nachricht genutzt werden.

    curl --request DELETE \
    --url https://example.com/messages/<messages-id> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Planer

In diese Kategorie fällt alles, was mit dem Stundenplan oder dem Terminkalender zu tun hat. Dabei ist der Stundenplan ein semesterabhängiger Wochenplan, der wöchentlich wiederkehrende Termine enthält, die entweder selbst eingetragen wurden oder aufgrund von besuchten Veranstaltungen dort hinein gelangen.

Schemata

Schema "calendar-events"

Ressourcen dieses Typs sind selbst in den Terminkalender eingetragene Termine.

Attribute

Attribut Beschreibung
title der Titel des Eintrags
description die Beschreibung des Eintrags
start der Beginn des Eintrags (ISO 8601)
end das Ende des Eintrag (ISO 8601)
categories die Kategorie des Eintrags (als String)
location der Ort des Eintrags
mkdate das Erstellungsdatum des Eintrags
chdate das Datum der letzten Änderung des Eintrags
recurrence Informationen über Wiederholungen des Eintrags

Relationen

Relation Beschreibung
owner der Nutzer, der den Eintrag erstellt hat

Schema "course-events"

Ressourcen dieses Typs repräsentieren einmalige Termine von belegten Veranstaltungen.

Attribute

Attribut Beschreibung
title der Titel des Eintrags
description die Beschreibung des Eintrags
start der Beginn des Eintrags (ISO 8601)
end das Ende des Eintrag (ISO 8601)
categories die Kategorie des Eintrags (als String)
location der Ort des Eintrags
mkdate das Erstellungsdatum des Eintrags
chdate das Datum der letzten Änderung des Eintrags
recurrence Informationen über Wiederholungen des Eintrags

Relationen

Relation Beschreibung
owner die Veranstaltung, zu der der Eintrag gehört

Schema "schedule-entries"

Ressourcen dieses Typs stellen Einträge in den Stundenplan dar, die ein Nutzer selbst eingetragen hat.

Attribute

Attribut Beschreibung
title der Titel des Eintrags
description die Beschreibung des Eintrags
start die Uhrzeit des Beginns des Eintrags ("hh:mm")
end die Uhrzeit des Endes des Eintrags ("hh:mm")
weekday der Wochentag des Eintrags (0-6)
color die Farbe des Eintrags ("#rrggbb")

Relationen

Relation Beschreibung
owner der Nutzer, der den Eintrag erstellt hat

Schema "seminar-cycle-dates"

Ressourcen dieses Typs stellen Einträge in den Stundenplan dar, die sich aus den regelmäßigen Terminen einer Veranstaltung zusammensetzen.

Attribute

Attribut Beschreibung
title der Titel des Eintrags
description die Beschreibung des Eintrags
start die Uhrzeit des Beginns des Eintrags ("hh:mm")
end die Uhrzeit des Endes des Eintrags ("hh:mm")
weekday der Wochentag des Eintrags (0-6)
recurrence Informationen über Wiederholungen des Eintrags
locations alle Orte, an denen dieser Eintrag stattfindet

Relationen

Relation Beschreibung
owner die Veranstaltung, zu der der Eintrag gehört

Alle Kalendereinträge auslesen

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

Mit dieser Route kann der Kalender des Nutzer abgefragt werden. Ohne weitere Parameter werden alle Einträge der nächsten zwei Wochen zurück geliefert.

HTTP Request

GET /users/{id}/events

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

Parameter Beschreibung
filter[timestamp] Startzeitpunkt der gelieferten Kalendereinträge (als Sekunden seit dem 01.01.1970)

Wenn "filter[timestamp]" nicht gesetzt ist, werden alle Kalendereinträge der nächsten zwei Wochen zurück geliefert.

Mittels "filter[timestamp]" kann dieser Startzeitpunkt verändert werden. Es werden jedoch immer Kalendereinträge der nächsten zwei Wochen ausgeliefert.

Autorisierung

Jeder Nutzer darf diese Route für sich selbst verwenden. Andere Nutzer haben nur Zugriff auf ihre eigenen Kalender.

Alle Kalendereinträge (iCalendar)

curl --request GET \
    --url https://example.com/users/<ID>/events.ics \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route kann der Kalender des Nutzer abgefragt werden. Die Daten werden im iCalendar-Datenformat ausgeliefert. Es werden alle Kalendereinträge zurück gegeben.

HTTP Request

GET /users/{id}/events.ics

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder Nutzer darf diese Route für sich selbst verwenden. Andere Nutzer haben nur Zugriff auf ihre eigenen Kalender.

Alle Termine einer Veranstaltung

curl --request GET \
    --url https://example.com/courses/<ID>/events \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route können alle Termine einer Veranstaltung abgefragt werden.

HTTP Request

GET /courses/{id}/events

Parameter Beschreibung
id die ID der Veranstaltung

URL-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset (siehe Paginierung)
page[limit] 30 das Limit (siehe Paginierung)

Autorisierung

Die Termine einer Veranstaltung sind für alle Teilnehmenden sichtbar.

Stundenplan auslesen

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

Mit dieser Route kann man seinen Stundenplan abfragen. Wird kein filter-Parameter angegeben, wird der Stundenplan des aktuellen Semesters ausgeliefert.

HTTP Request

GET /users/{id}/schedule

Parameter Beschreibung
id die ID des Nutzers

URL-Parameter

Parameter Default Beschreibung
filter[timestamp] Beginn des aktuellen Semesters Startzeitpunkt des gewünschten Semesters (in Sekunden seit 01.01.1970)

Autorisierung

Nur der eigene Stundenplan kann ausgelesen werden.

Eigene Stundenplaneinträge

curl --request GET \
    --url https://example.com/schedule-entries/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route kann man einen einzelnen, selbst verfassten Eintrag in den Stundenplan auslesen.

HTTP Request

GET /schedule-entries/{id}

Parameter Beschreibung
id die ID des Eintrags

URL-Parameter

keine URL-Parameter

Autorisierung

Nur der Nutzer, der den Eintrag verfasst hat, darf den Eintrag auch auslesen.

Regelmäßige Veranstaltungstermine auslesen

curl --request GET \
    --url https://example.com/seminar-cycle-dates/<ID> \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Beschreibung

HTTP Request

GET /seminar-cycle-dates/{id}

Parameter Beschreibung
id die ID des Termins

URL-Parameter

keine URL-Parameter

Autorisierung

Alle Teilnehmenden einer Veranstaltung können den Termin sehen.

Räume/Gebäude

In dieser Kategorie ist alles versammelt, was mit Ressourcenverwaltung zu tun hat.

Schema "resources-objects"

Alle Ressourcenobjekte der Ressourcenverwaltung werden mit diesem Schema repräsentiert.

Attribute

Attribut Beschreibung
name der Name der Ressource
description die Beschreibung der Ressource
is-room Handelt es sich bei dieser Ressource um einen Raum?
multiple-assign Darf diese Ressource zeitgleich mehrfach belegt werden?
requestable Kann man zu dieser Ressource eine Raumanfrage stellen?
lockable Ist diese Ressource betroffen von einer globalen Sperrzeit?
mkdate Erstellungsdatum
chdate Änderungsdatum

Relationen

Relation Beschreibung
category Kategorie der Ressource

Schema "resources-categories"

Dieses Schema beschreibt Ressourcenarten.

Attribute

Attribut Beschreibung
name der Name der Art
description die Beschreibung der Art
system
is-room Handelt es sich bei dieser Art um einen Raum?
icon Nummer des zu verwendenden Icons

Relationen

keine Relationen

Schema "resources-assign-events"

Alle Ressourcenbelegungen werden mit diesem Schema abgebildet.

Attribute

Attribut Beschreibung
repeat-mode in welchem Abstand und in welcher Frequenz wird diese Ressourcenbelegung ausgeführt
start das Datum des Beginns der Belegung
end das Datum des Endes der Belegung
owner-free-text Freitextangabe für den Besitzer dieser Belegung

Relationen

Relation Beschreibung
owner (optional) der Besitzer der Belegung
resources-object die belegte Ressource

Alle Ressourcen

curl --request GET \
    --url https://example.com/resources-objects \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Diese Route liefert alle Ressourcenobjekte.

HTTP Request

GET /resources-objects

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder eingeloggte Nutzer kann die Liste der Ressourcenobjekte sehen.

Alle Belegungen einer Ressource

curl --request GET \
    --url https://example.com/resources-objects/<ID>/assignments \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route können die Belegungen einer Ressource abgefragt werden.

HTTP Request

GET /resources-objects/{id}/assignments

Parameter Beschreibung
id die ID des Ressourcenobjekts

URL-Parameter

Parameter Default Beschreibung
filter[start] (heute) optional; Zeitpunkt (in Sekunden seit 1.1.1970), ab dem die Belegungen angezeigt werden sollen
filter[end] (morgen) optional; Zeitpunkt (in Sekunden seit 1.1.1970), bis zu dem die Belegungen angezeigt werden sollen

Die Parameter "filter[start]" und "filter[end]" müssen als Integer angegeben werden (Sekunden seit 1.1.1970 00:00:00 UTC). Werden sie nicht angegeben, werden die Belegungen des heutigen Tages angezeigt.

Autorisierung

Jeder eingeloggte Nutzer kann die Liste der Ressourcenbelegungen sehen.

Semester

Semester geben einen bestimmten Studien-Zeitraum in Stud.IP an. Sie dienen auch als Filter für Veranstaltungen und Suchen.

Schema "semesters"

Neben dem Titel und der Beschreibung beinhalten Semester Meta-Daten über Start- und End-Zeitpunkt des Semesters

Attribute

Attribut Beschreibung
title Name des Semesters
description Weitere Angaben zum Semester
start Startzeitpunkt
end Endzeitpunkt

Relationen

keine

Alle Semester

GET /semesters

   curl --request GET \
       --url https://example.com/semesters \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Ein Semester

GET /semesters/{id}

   curl --request GET \
       --url https://example.com/semesters/<semester-id> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Veranstaltungen

Schema "courses"

Attribute

Attribut Beschreibung
course-number ID des Kurses
title Titel des Kurses
subtitle Untertitel des Kurses
course-type Art des Kurses (Seminar, Vorlesung...)
description Beschreibung des Kurses
location Ort der Veranstaltung
miscellaneous sonstiges

Relationen

Relation Beschreibung
institute Die zugewiesene Institution
start-semester Anfangs-Semester der Veranstaltung
end-semester End-Semester der Veranstaltung
files Referenz auf Files innerhalb der Veranstaltung
documents Referenz auf Dokumente innerhalb der Veranstaltung
document-folders Ordner für Dateien innerhalb der Veranstaltung

Schema "course-memberships"

Zeigt die Teilnahme an einer Veranstaltung mit Ihrer Rolle an.

Attribute

Attribut Beschreibung
permission Rolle des Nutzers (Autor, Dozent, etc...)
position Anordnung in der Teilnehmer-Liste
group Anordnung in der Teilnehmer-Liste
mkdate Erstellungsdatum
label die "Funktion" des Teilnehmers (s. Weboberfläche)
notification Bekomme ich einmal am Tag eine E-Mail-Benachrichtigung über neue Inhalte in dieser Veranstaltung?
comment Teilnehmerkommentar für Lehrende
visible Sichtbarkeit im Kurs

Das Feld "visible" ist nur für einen selbst bzw. die Lehrenden der Veranstaltung zu sehen.

Relationen

Relation Beschreibung
course Die Veranstaltung für die Teilnehmer
user Nutzer der Veranstaltung

URL-Parameter

Parameter Default Beschreibung
page[offset] 0 der Offset (siehe Paginierung)
page[limit] 30 das Limit (siehe Paginierung)
filter[q] - ein Suchbegriff (mind. 3 Zeichen)
filter[fields] all in welchen Feldern gesucht werden soll
filter[semester] all in welchem Semester gesucht werden soll

Der Parameter "filter[fields]" darf folgende Werte annehmen: 'all', 'title_lecturer_number', 'title', 'sub_title', 'lecturer', 'number', 'comment', 'scope'.

Alle Veranstaltungen

Mit dieser Route können alle Veranstaltungen ausgelesen werden.

HTTP Request

GET /courses

Parameter

Diese Route benötigt keine Parameter

Autorisierung

Jeder eingeloggte Nutzer kann diese Route verwenden.

Parameter

Parameter Beschreibung
id ID des Kurses

Autorisierung

Jeder Teilnehmer des Kurses kann diese Route nutzen.

curl --request GET \
    --url https://example.com/courses \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Eine Veranstaltung

Gibt eine Veranstaltung wieder.

HTTP Request

GET /courses/{id}

Parameter

Parameter Beschreibung
id ID des Kurses

Autorisierung

Jeder Teilnehmer des Kurses oder Root kann diese Route nutzen.

   curl --request GET \
       --url https://example.com/courses/<course-id> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Alle Veranstaltungen eines Nutzers

Gibt alle Veranstaltungen eines Nutzers zurück.

HTTP Request

GET /users/{id}/courses

Parameter

Parameter Beschreibung
id ID des Nutzers

Autorisierung

Jeder eingeloggte Nutzer kann diese Route nutzen.

   curl --request GET \
       --url https://example.com/users/<user-id>/courses \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Teilnahmen einer Veranstaltung

Gibt alle Kurse mit dem jeweiligen Teilnehmerstatus eines Nutzers zurück.

HTTP Request

GET /courses/{id}/memberships

Parameter

Parameter Beschreibung
id ID des Kurses

Autorisierung

Nutzer mit mindestens Adminstatus oder Teilnehmer des Kurses können diese Route benutzen.

   curl --request GET \
       --url https://example.com/courses/<course-id>/memberships \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

IDs der Teilnahmen

Gibt die Referenzen auf die Teilnehmer eines Kurses zurück.

HTTP-Request

GET /courses/{id}/relationships/memberships

Parameter

Parameter Beschreibung
id ID des Kurses

Autorisierung

Nutzer mit mindestens Adminstatus oder Teilnehmer des Kurses können diese Route benutzen.

   curl --request GET \
       --url https://example.com/courses/<course-id>/relationships/memberships \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Eine Teilnahme auslesen

   curl --request GET \
       --url https://example.com/course-memberships/<ID> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Gibt eine Teilnahme wieder.

HTTP Request

GET /course-memberships/{id}

Parameter

Parameter Beschreibung
id ID der Teilnahme

Autorisierung

Nur der Teilnehmer selbst kann die Teilnahme auslesen

Eine Teilnahme ändern

   curl --request PATCH \
       --url https://example.com/course-memberships/<ID> \
       --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
       --header "Content-Type: application/vnd.api+json" \
       --data '{"data": {
           "type": "course-memberships",
           "id": "<ID>",
           "attributes": {"group":2,"visible":"no"}
       }}'

Mit dieser Route kann man die Attribute einer Teilnahme an einer Veranstaltung ändern.

HTTP Request

PATCH /course-memberships/{id}

Parameter

Parameter Beschreibung
id ID der Teilnahme

Autorisierung

Nur der Teilnehmer selbst kann die Teilnahme ändern.

Wiki

Schema "wiki-pages"

Neben dem Inhalt und Namen enthält jede Wiki-Seite Metadaten zur aktuellen Version.

Attribute

Attribut Beschreibung
keyword Der Name der Wiki-Seite
content Der Inhalt der Wiki-Seite
chdate Das Datum der letzten Änderung
version Die aktuelle Versionsnummer

Relationen

Relation Beschreibung
author Der Verfasser der Wiki-Seite
range Der Range einer Wiki-Seite ist der entsprechende Kurs

Wiki-Seiten eines Kurses

GET /courses/{id}/wiki-pages

Parameter

Parameter Beschreibung
id Die ID des Kurses
  curl --request GET \
      --url https://example.com/courses/<COURSE-ID>/wiki-pages \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "meta": {
    "page": {
      "offset": 0,
      "limit": 30,
      "total": 2
    }
  },
  "links": {
    "first": "/?page[offset]=0&page[limit]=30",
    "last": "/?page[offset]=0&page[limit]=30"
  },
  "data": [
    {
      "type": "wiki-pages",
      "id": "a07535cf2f8a72df33c12ddfa4b53dde_ulyq",
      "attributes": {
        "keyword": "ulyq",
        "content": "Es gibt im Moment in diese Mannschaft, oh, einige Spieler vergessen ihren Profi was sie sind. Ich lese nicht sehr viele Zeitungen, aberich habe geh\u00f6rt viele Situationen. Erstens: Wir haben nicht offensivgespielt.",
        "chdate": "2019-04-23T12:10:26+02:00",
        "version": 1
      },
      "relationships": {
        "author": {
          "data": {
            "type": "users",
            "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
          },
          "links": {
            "related": "jsonapi.php/v1/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
          }
        },
        "range": {
          "data": {
            "type": "courses",
            "id": "a07535cf2f8a72df33c12ddfa4b53dde"
          },
          "links": {
            "related": "jsonapi.php/v1/courses/a07535cf2f8a72df33c12ddfa4b53dde"
          }
        }
      }
    },
    {
      "type": "wiki-pages",
      "id": "a07535cf2f8a72df33c12ddfa4b53dde_yxilo",
      "attributes": {
        "keyword": "yxilo",
        "content": "Es gibt im Moment in diese Mannschaft, oh, einige Spieler vergessen ihren Profi was sie sind. Ich lese nicht sehr viele Zeitungen, aberich habe geh\u00f6rt viele Situationen. Erstens: Wir haben nicht offensivgespielt.",
        "chdate": "2019-04-23T12:10:26+02:00",
        "version": 1
      },
      "relationships": {
        "author": {
          "data": {
            "type": "users",
            "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
          },
          "links": {
            "related": "jsonapi.php/v1/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
          }
        },
        "range": {
          "data": {
            "type": "courses",
            "id": "a07535cf2f8a72df33c12ddfa4b53dde"
          },
          "links": {
            "related": "jsonapi.php/v1/courses/a07535cf2f8a72df33c12ddfa4b53dde"
          }
        }
      }
    },
    "[...]"
  ]
}

Wiki-Seite

Gibt eine Wiki-Seite zurück.

GET /wiki-pages/{id}

Parameter Beschreibung
id Die ID der Wiki-Seite
  curl --request GET \
      --url https://example.com/wiki-pages/<ID> \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Der Request liefert JSON ähnlich wie dieses:

{
  "data": {
    "type": "wiki",
    "id": "48101a5a47c34f80999cc01266b32536_tastyTest",
    "attributes": {
      "keyword": "tastyTest",
      "content": "This is dsdsadsad",
      "chdate": "2018-06-05T14:12:29+02:00",
      "version": 1
    },
    "relationships": {
      "author": {
        "data": {
          "type": "users",
          "id": "76ed43ef286fb55cf9e41beadb484a9f"
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
        }
      },
      "range": {
        "data": {
          "type": "courses",
          "id": "48101a5a47c34f80999cc01266b32536"
        },
        "links": {
          "related": "/stud35/plugins.php/argonautsplugin/courses/48101a5a47c34f80999cc01266b32536"
        }
      }
    },
    "links": {
      "self": "/stud35/plugins.php/argonautsplugin/courses/48101a5a47c34f80999cc01266b32536/wiki/tastyTest"
    }
  }
}

Wiki-Seite anlegen

Legt eine Wiki-Seite an.

POST /courses/{id}/wiki-pages

Parameter Beschreibung
id Die ID der Veranstaltung
  curl --request POST \
      --url https://example.com/courses/<COURSE-ID>/wiki \
      --header "Content-Type: application/vnd.api+json" \
      --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
      --data
      '{"data": {"type": "wiki-pages","attributes": {"keyword": "testing","content": "wiki created"}}}'

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Wiki-Seite ändern

Aktualisiert eine Wiki-Seite.

PATCH /wiki-pages/{id}

Parameter Beschreibung
id Die ID der Wiki-Seite

curl --request PATCH \ --url https://example.com/wiki-pages/ \ --header "Content-Type: application/vnd.api+json" \ --header "Authorization: Basic echo -ne "test_autor:testing" | base64" \ --data '{"data": {"type": "wiki-pages","attributes": {"content": "wiki changed"}}}' ```

Autorisierung

Der Nutzer sollte Mitglied des entsprechenden Kurses sein.

Paginierung

Viele Ergebnisse von GET-Routen werden paginiert zurückgeliefert. Dabei wird die Gesamtheit aller Ergebnisse auf mehrere Seiten verteilt und man erhält jeweils nur einen Ausschnitt. Dieser Ausschnitt kann durch die folgenden URL-Parameter beeinflusst werden

Page-Parameter Beschreibung
page[offset] der Paginierungsoffset
page[limit] das Paginierungslimit

Der 'page'-Parameter wird der JSON:API-Spezifikation entsprechend verwendet.

Fehler

Die Stud.IP-JSON:API verwendet die Fehler-Codes, die auch in der JSON-API-Spezifikation verwendet werden.

Fehler Code Bedeutung
401 Unauthorized – Sie haben nicht die erforderliche Berechtigung.
403 Forbidden – Die gewünschte Operation steht nicht zur Verfügung.
404 Not Found – Die gewünschte Ressource oder Relation konnte nicht gefunden werden.
409 Conflict – Beim Anlegen oder Ändern von Ressourcen oder Relationen werden Beschränkungen im Stud.IP verletzt. Beispiel: Eine Ressource falschen Typs soll einer Relation hinzugefügt werden.
500 Internal Server Error – Es gibt ein Problem auf dem Server. Versuchen Sie es später erneut!

Discovery

Auch wenn JSON:APIs von Haus aus einiges mehr "discoverable" als herkömmliche REST-APIs sind, schadet es nicht, eine spezielle Route anzubieten, um alle verfügbaren Routen anzuzeigen.

Schemata

Schema "slim-routes"

Ressourcen vom Typ "slim-routes" repräsentieren die aktiven Routen der Stud.IP-JSON:API.

Attribute

Attribut Beschreibung
methods ein Vektor von HTTP-Verben wie GET, POST, PATCH und DELETE
pattern ein URI-Pattern wie "/file-refs/{id}"

Relationen

keine Relationen vorhanden

Alle Routen anzeigen

curl --request GET \
    --url https://example.com/discovery \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Mit dieser Route erhält man eine Liste aller aktiven Routen der Stud.IP-JSON:API.

HTTP Request

GET /discovery

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder eingeloggte Nutzer darf diese Route aufrufen.

Stud.IP-System

Alle Routen, die mit dem Stud.IP-System an sich zu tun haben, sind in dieser Kategorie versammelt.

Schemata

Schema "studip-properties"

Ausgewählte Konfigurationseinstellungen und Merkmale der Stud.IP-Installation werden mit diesem Schema abgebildet.

ID

Die ID der Einstellung ist kein MD5-Hash sondern ein festes Kürzel für eine Einstellung/ein Merkmal.

Attribute

Attribut Beschreibung
description eine Beschreibung der Einstellung/des Merkmals
value der Wert der Einstellung/des Merkmals

Relationen

keine Relationen vorhanden

Alle Stud.IP-Properties auslesen

curl --request GET \
    --url https://example.com/studip/properties \
    --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Liefert alle Stud.IP-Einstellungen/Merkmale

HTTP Request

GET /studip/properties

URL-Parameter

keine URL-Parameter

Autorisierung

Jeder eingeloggte Nutzer darf diese Route aufrufen.