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.