Cevi.DB API

Die CeviDB bietet eine API, mit der Personen- und Gruppen-Daten aus der Datenbank ausgelesen werden können. Die API erlaubte es aber nicht Daten in der CeviDB zu verändern.

Allgemeine Hinweisee

Die Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet JSON als Datenformat. Der Zugriff über die Schnittstelle erfordert die Zugangsdaten eines registrierten Benutzers. Die Rechte der Schnittstelle entsprechen dann denn Rechten des verwendeten Nutzers. Beim Login wird ein user token generiert, das danach bei jeder Anfrage mitgesendet werden muss.

Ablauf einer Abfrage

1. Login-Anfrage mit eMail und Passwort senden
2. Aus Antwort user token auslesen
3. Anfrage für Gruppen- oder Personendaten senden (mit eMail und user token)
4. Aus Antwort gewünschte Daten auslesen

Wichtig: Passwörter dürfen nicht hardcoded im Programmcode hinterlegt werden. Passwörter im Programmcode sind eine Sicherheitsrisiko. Soll ein Programm ohne Interaktion mit einem Benutzer ausgeführt werden, so kann das user token im Programmcode hinterlegt werden. Gelingt es einem Angreifer das Token auszulesen, so erhält er nur eingeschränkte Lese-Rechte. Ein gestohlenes Passwort würde ihm erlauben, sich mit den vollen Benutzerrechten des Besitzers einzuloggen. Bitte informiert cevidb@cevi.ch, wenn ihr ein Skript erstellt und ein user token hinterlegt.

Erstes Login

Um sich anzumelden, muss ein POST-Request an https://db.cevi.ch/users/sign_in.json gesendet werden. Als Parameter müssen person[email] und person[password] übergeben werden.

Beispiele

TODO

Endpunkte

Endpunkt	URL	Beispiel (gid=1, pid=2)
Gruppen	https://db.cevi.ch/groups/<gid>.json	https://db.cevi.ch/1.json
Personen in Gruppe	https://db.cevi.ch/groups/<gid>/people.json	https://db.cevi.ch/1/people.json
Details zu Person	https://db.cevi.ch/groups/<gid>/people/<pid>.json	https://db.cevi.ch/1/people/2.json

Hinweis: Wird versucht ohne Gruppen-Angabe auf eine Person zuzugreifen (https://db.cevi.ch/people/<pid>.json) so wird die Anfrage auf die Haubtgruppe der Person weitergeleitet. Allerdings wird bei dieser Weiterleitung der Query-String ignoriert, so dass ein 401 Authorization Required Fehler resultiert. Aus der Fehlermeldung kann jedoch die korrekte URL bestimmt werden.