105
Bearbeitungen
Änderungen
Zur Navigation springen
Zur Suche springen
Fix Typo
Die CeviDB bietet eine <abbr>API</abbr>, mit der Personen- und Gruppen-Daten aus der Datenbank ausgelesen werden können. Die <abbr>API</abbr> erlaubte es aber '''nicht''', Daten in der CeviDB zu verändern.
=== Allgemeine Hinweise ===
Die Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet [http://de.wikipedia.org/wiki/JavaScript_Object_Notation 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 <code>user token</code> generiert, das danach bei jeder Anfrage mitgesendet werden muss.
==== Spender-Tool des RV ====
Die API wird vom Spender-Tool des RVs verwendet. Das Tool ist in Python geschrieben und ist freie Software. Es kann von [https://github.com/nchiapol/cevidbtool Github] heruntergeladen werden.
=== Ablauf einer Abfrage === # Login-Anfrage mit Email und Passwort senden# Aus Antwort <code>user token</code> auslesen# Anfrage für Gruppen- oder Personendaten senden (mit Email und <code>user token</code>)# Aus Antwort gewünschte Daten auslesen
'''Wichtig''': Passwörter dürfen nicht hardcoded im Programmcode hinterlegt werden. Passwörter im Programmcode sind ein Sicherheitsrisiko. Soll ein Programm ohne Interaktion mit einem Benutzer ausgeführt werden, so kann das <code>user token</code> 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 [mailto:cevidb@cevi.ch cevidb@cevi.ch], wenn ihr ein Skript erstellt und ein <code>user token</code> 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 <code>person[email]</code> und <code>person[password]</code> übergeben werden.
==== Beispiele ====
'''Python:'''
<syntaxhighlight lang="python" line="line">
</syntaxhighlight>
'''Wichtig''': Damit die https-Verbindung klappt, müssen die CA-Zertifikate verfügbar sein. In Python kann die Zertifikatdatei mit dem verify Keyword-Argument der post-Funktion definiert werden.
=== User Token verwalten ===
Das <code>user token</code> ist über mehrere Logins konstant. Dadurch kann das Token in Programmen hinterlegt werden, die ohne Benutzer-Interaktion funktionieren sollen. Um ein bestehendes Token zu löschen oder ein neues Token zu generieren, können folgende Anfragen verwendet werden:
{| class="wikitable"
|}
Als Parameter müssen wie beim Login <code>person[email]</code> und <code>person[password]</code> übergeben werden.
=== Daten abfragen ===
Sobald das Authentication Token bekannt ist, können verschiedene Endpunkte abgefragt werden. Die URL entspricht dabei der URL im Browser, endet aber auf <code>.json</code>
Bei jeder Abfrage müssen zudem die Email-Adresse und das <code>user token</code> mitgesendet werden. Dazu bestehen zwei Möglichkeiten:
* als URL-Parameter: <code>.json?user_email=ceviname@cevi.ch&user_token=123456</code>* als Headers: <code>X-User-Email: ceviname@cevi.ch, X-User-Token: 123456</code> und <code>Accept: application/json</code>
Weiter können weitere GET-Parameter (analog zur “richtigen” CeviDB) angehängt werden. Am besten führt man das Gewünschte in der CeviDB aus (zum Beispiel Sortieren nach Rollen) und kopiert die URL, ändert die Endung zu <code>.json</code>.
==== Beispiele ====
Normale Abfrage mit Python:
<syntaxhighlight lang="python" line="1">
data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.
</syntaxhighlight>
=== Endpunkte ===
{| class="wikitable"
!Endpunkt
|Gruppen <code><gid></code>
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>.json
|<nowiki>https://db.cevi.ch/groups/1.json</nowiki>
|-
|Personen in Gruppe <code><gid></code>
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people.json
|<nowiki>https://db.cevi.ch/groups/1/people.json</nowiki>
|-
|Details zu Person <code><pid></code>
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people/<pid>.json
|<nowiki>https://db.cevi.ch/groupus/1/people/2.json</nowiki>
|}
'''Hinweis: '''Wird versucht ohne Gruppen-Angabe auf eine Person zuzugreifen (<code><nowiki>https://db.cevi.ch/people/</nowiki><pid>.json</code>) so wird die Anfrage auf die Hauptgruppe der Person weitergeleitet. Allerdings wird bei dieser Weiterleitung der Query-String ignoriert, so dass ein <code>401 Authorization Required</code> Fehler resultiert. Aus der Fehlermeldung kann jedoch die korrekte <abbr>URL</abbr> bestimmt werden.
[[Kategorie:CeviDB]]
