REST-API

Der IServ Portalserver enthält eine REST-API, über die externe Dienste die gesamte Benutzer- und Gruppenverwaltung fernsteuern können. Zum Schutz gegen unbefugte Zugriffe ist diese durch spezielle Zugangsdaten abgesichert und auf bestimmte IP-Adressbereiche eingeschränkt, die im System als root konfiguriert werden müssen. In Zukunft werden wir auch weitere IServ-Module in diese API einbinden.

Warnung

Aufgrund mangelnder Nutzung im Gegensatz zum erhöhten Pflegebedarf und Inkompatibilitäten mit der zukünftigen Entwicklung wurde die aktuelle API abgekündigt und sollte nicht weiter verwendet werden. Ein Großteil der Funktionen kann bereits vom IDM (https://idm.demo-iserv.de/iserv/idm/api/v1/docs?ui=redocs) übernommen werden.

Bemerkung

Die hier beschriebene Funktionalität wird nur noch für Bestandskunden übergangsweise angeboten. Für seit Juni 2022 installierte Server besteht die Möglichkeit zur Nutzung der veralteten API nicht mehr. Bitte verwenden Sie in diesem Fall die API des IDMs.

Einrichtung

Zuerst muss als root in der Konsole ein API-Benutzer erstellt werden. Im Beispiel wird der Benutzer „test“ erstellt, der von 10.0.0.0/8 zugreifen darf. Es wird automatisch ein sicheres Passwort generiert und ausgegeben.

# iservapiuser add test 10.0.0.0/8
SMQQQcFKXoySNfFRv/5SzurEyVxhPosx

Alle API-Benutzer mit letztem Login anzeigen:

# iservapiuser
test                    10.0.0.0/8              2016-11-15 18:03:17+01

Auf geschützten Entwicklungsservern kann zum Testen das Passwort „nopass“ direkt in der Datenbank gesetzt werden. Auf Produktivservern sollte aber unbedingt das generierte verwendet werden.

# psql -c "UPDATE api_user SET crypt = perl_crypt('nopass', 'xx') WHERE login = 'test'"
UPDATE 1

Test

Eine komplette interaktive Dokumentation der API kann nun im Webbrowser abgerufen werden. Zur Anmeldung wird der oben erstellte API-Benutzer verwendet.

https://meine-schule.de/iserv/api/docs/

Mit folgender Abfrage kann zum Beispiel die Benutzerliste abgerufen werden:

# curl -s -u test:nopass -X GET --header 'Accept: application/json' \
    'https://meine-schule.de/iserv/api/IServ/Core/Entity/Group' | jq .
[
  {
    "account": "a.a",
    "name": "A a",
    "created": "2015-07-09T00:00:00+02:00",
    "createdBy": "test.user",
    "owner": "test.user",
    "_id": "a.a"
  },
[...]

Oder die Gruppe „string“ erstellt werden:

# curl -s -u test:nopass -X POST --header 'Content-Type: application/json' \
    --header 'Accept: application/json' -d '{  "name": "string" }' \
    'https://meine-schule.de/iserv/api/IServ/Core/Entity/Group' | jq .
{
  "deleted": null,
  "account": "string",
  "name": "string",
  "users": [],
  "created": null,
  "createdBy": null,
  "privileges": [],
  "home": null,
  "owner": null,
  "deletedBy": null,
  "flags": []
}

Die API ist sehr neu und kann noch Fehler enthalten. Bei Problemen bitten wir um eine entsprechende Rückmeldung.