105
Bearbeitungen
Änderungen
Beispiele mit Formatierung hinzugefügt
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 Hinweisee 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
=== 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:'''
import requests
email = "ceviname@cevi.ch"
passwort = "123456"
res = requests.post('https://db.cevi.ch/users/sign_in.json?person[email]='+email+'&person[password]='+passwort)
token = res.json()["people"][0]["authentication_token"]
</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"!Request Typ!URL|-|post|[https://db.cevi.ch/users/token.json https://db.cevi.ch/users/token.json]|-|delete|[https://db.cevi.ch/users/token.json https://db.cevi.ch/users/token.json]|}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="line">import requests# vor diesem Teil muss natürlich das Token ausgelesen und gespeichert werdenemail = "ceviname@cevi.ch"token= "1a2b3c"res = requests.post('https://db.cevi.ch/groups/5/people.json?user_email='+email+'&user_token='+token)data= res.json()["people"]</syntaxhighlight>Normale Anfrage mit der Shell:<syntaxhighlight lang="bash" line="line">wget --header "X-User-Email: ceviname@cevi.ch" --header "X-User-Token: 1a2b3c" \ --header "Accept: application/json" https://db.cevi.ch/groups/5/people.json -O people.jsoncat people.json</syntaxhighlight>Anfrage mit Sortierung mit Python:<syntaxhighlight lang="python" line="line"># nach Login, Variable token ist definiert# gewünscht ist eine Sortierung nach Rollen# der Teil sort=roles&sort_dir=asc sortiert nun nach den Rollen, die höchste (z.B. AL) ist dann auch im json-File zuerst drin.res = requests.get('https://db.cevi.ch/groups/5/people.json?sort=roles&sort_dir=asc&user_email=ceviname@cevi.ch&user_token='+token)data = res.json()['people']</syntaxhighlight>
==== Endpunkte ====
{| class="wikitable"