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.

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.