Nutzer*innen

Nutzer*innen (users) von Stud.IP-Installationen können mit den folgenden Routen abgefragt werden.

Schema `users`

Alle Nutzer*innen 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 `username` wird beim Login-Vorgang verwendet
formatted-name	der formatierte Echtname
family-name	der Nachname
given-name	der Vorname
name-prefix	evtl. vorangestellte Titel
name-suffix	evtl. nachgestellte Titel
permission	die globale Berechtigungsstufe
email	die E-Mail-Adresse
auth-plugin	Art der Authentifizerung (z.B. `ldap`)
locked	Account gesperrt?
lock-comment	ggf. Sperrhinweis
visible	Sichtbarkeitsstatus
matriculation-number	Matrikelnummer
gender	Geschlecht
preferred-language	eingestellte Sprache
mkdate	Erstellungsdatum
chdate	Änderungsdatum
phone	die Telefonnummer
cellphone	die Mobilnummer
address	die private Adresse
homepage	die URL der Homepage
hobby	Hobbies
cv	Lebenslauf
publication	Publikationen
focus	Schwerpunkte
motto	Motto

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

Die Sichtbarkeit der Attribute wie phone, homepage, address folgt den Sichtbarkeitseinstellungen, die Nutzer*innen vorgenommen haben.

Relationen

Relation	Beschreibung
activitystream	ein Link zum `activity stream`
blubber-postings	die Blubber
contacts	die Kontakte
courses	die Veranstaltungen als `dozent`
course-memberships	die Teilnahmen an Veranstaltungen
datafield-entries	zusätzliche Datenfelder
events	der Terminkalender
institute-memberships	die Institute
profile-categories	eigene Kategorien im Profil
schedule	der Stundenplan
status-groups	Gruppenzuordnungen
status-group-memberships	Mitgliedschaften in Gruppen

Schema `profile-categories`

Dieses Schema bildet die eigenen Kategorien im Profil eines Nutzers ab.

Attribute

Attribut	Beschreibung
title	Titel der Kategorie
content	Inhalt der Kategorie
priority	Anzeigereihenfolge im Profil
mkdate	Erstellungsdatum der Kategorie
chdate	Änderungsdatum der Kategorie

Relationen

Relation	Beschreibung
user	Besitzer der Kategorie

Alle `users`

curl --request GET \
    --url https://example.com/jsonapi.php/v1/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*innen im Stud.IP, die mit den credentials des JSON:API-Nutzenden auch in Stud.IP selbst gesehen werden dürfen. Die Ausgabe erfolgt paginiert und kann durch Angabe von Offset und Limit weitergeblättert werden.

HTTP Request

GET /users

Query-Parameter

curl --request GET \
     --url 'https://example.com/jsonapi.php/v1/users?filter[search]=test_autor'\
     --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`"

Parameter	Default	Beschreibung
page[offset]	0	der Offset
page[limit]	30	das Limit
filter[search]	%%%	der Suchbegriff, um Nutzer zu finden; mind. 3 Zeichen

Autorisierung

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

Sich selbst auslesen

curl --request GET \
    --url https://example.com/jsonapi.php/v1/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.

Einzelne Nutzende auslesen

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

Diese Route liefert einzelne, beliebige Nutzende zurück. Unsichtbare Nutzende 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 alle Nutzenden sehen. Gesperrte und unsichtbare Nutzende sind ansonsten nicht sichtbar.

Nutzende löschen

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

Diese Route löscht einen beliebigen Nutzenden.

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 Nutzende der Rechtestufe root andere Nutzende löschen. Man kann sich selbst nicht löschen.

Mitgliedschaften in Einrichtungen

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

Mit dieser Route erhält man die Mitgliedschaften in Einrichtungen von Nutzenden.

HTTP Request

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

Query-Parameter

Es werden keine Query-Parameter unterstützt.

Autorisierung

Diese Route kann von jedem autorisierten Nutzer verwendet werden.

Mitgliedschaften in Gruppen

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

Mit dieser Route erhält man die Mitgliedschaften in Gruppen von Nutzenden.

HTTP Request

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

Parameter

Parameter	Beschreibung
id	ID des Nutzers

Query-Parameter

Parameter	Default	Beschreibung
filter[range-id]	-	ID der Einrichtung oder Veranstaltung

Autorisierung

Diese Route kann von jedem autorisierten Nutzer verwendet werden, sofern der anzuzeigende Nutzer sichtbar ist.

Zuordnung zu Gruppen

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

Mit dieser Route erhält man die Gruppenzuordnungen von Nutzenden.

HTTP Request

GET http://example.com/api/users/{id}/status-groups

Parameter

Parameter	Beschreibung
id	ID des Nutzers

Query-Parameter

Parameter	Default	Beschreibung
filter[range-id]	-	ID der Einrichtung oder Veranstaltung

Autorisierung

Diese Route kann von jedem autorisierten Nutzer verwendet werden, sofern der anzuzeigende Nutzer sichtbar ist.

Eigene Kategorien im Profil

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

Mit dieser Route erhält man die vom Nutzer angelegten Kategorien im Profil.

HTTP Request

GET http://example.com/api/users/{id}/profile-categories

Parameter

Parameter	Beschreibung
id	ID des Nutzers

Query-Parameter

Es werden keine Query-Parameter unterstützt.

Autorisierung

Diese Route kann von jedem autorisierten Nutzer verwendet werden, sofern der anzuzeigende Nutzer sichtbar ist.

Nutzer*innen

Schema users

Attribute

Relationen

Schema profile-categories

Attribute

Relationen

Alle users

HTTP Request

Query-Parameter

Autorisierung

Sich selbst auslesen

HTTP Request

Query-Parameter

Autorisierung

Einzelne Nutzende auslesen

HTTP Request

Query-Parameter

Autorisierung

Nutzende löschen

HTTP Request

Query-Parameter

Autorisierung

Mitgliedschaften in Einrichtungen

HTTP Request

Query-Parameter

Autorisierung

Mitgliedschaften in Gruppen

HTTP Request

Parameter

Query-Parameter

Autorisierung

Zuordnung zu Gruppen

HTTP Request

Parameter

Query-Parameter

Autorisierung

Eigene Kategorien im Profil

HTTP Request

Parameter

Query-Parameter

Autorisierung

Schema `users`

Schema `profile-categories`

Alle `users`