CeviDB API: Unterschied zwischen den Versionen

Aus CeviWiki
Zur Navigation springen Zur Suche springen
(Information zum Tool "cevi-versand" (Ich denke, das passt hier rein, da das RV Spender-Tool ja auch hier erwähnt wird?))
 
(5 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
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.
+
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. Es gibt zwei Methoden, um Daten automatisiert auszulesen. Beide sind hier kurz erklärt.
  
===Allgemeine Hinweise===
+
===User-Tokens===
 +
Dies ist ein Token, dass persönlich ist. Das heisst, es hat den gleichen Zugriff (lesen) wie der Ersteller. Auf lange Sicht wird diese Art eventuell auch wieder abgeschaltet.
 +
 
 +
===Service-Tokens===
 +
Dies ist die neue Version der Abfragen. Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "ofizielle" Dokumentation auf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/07_service_accounts.md]. Für die Service Tokens kann ganz genau eingestellt werden, welche Berechtigungen sie haben. Sie können auf einer Gruppe erstellt werden (auf der Gruppe im Menu oben auf "Api-Keys", <nowiki>https://db.cevi.ch/groups/GRUPPE/service_tokens</nowiki>)
 +
 
 +
<br />
 +
 
 +
===API===
 +
Die API wird von beiden, User-Tokens und Service-Tokens verwendet. Die offizielle Dokumentation finded ihr auch auf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md]. Untenstehend sind doch noch einige kurze Anleitungen und Informationen gesammelt. Sie sind für die User-Tokens geschrieben. Für den Gebrauch von Service-Tokens ändern sich die Endpunkte nicht, nur die Parameter ändern sich von <syntaxhighlight lang="bash">
 +
user_email=info@cevi.ch&user_token=AABBCC
 +
</syntaxhighlight>hin zu<syntaxhighlight lang="bash">
 +
token=DDEEFF
 +
</syntaxhighlight>
 +
 
 +
====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.
 
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.
====Tools====
+
 
=====Spender-Tool des RV=====
+
=====Tools=====
 +
======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.
 
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.
=====Couvertgenerator=====
+
======Couvertgenerator======
 
Das Tool [https://github.com/lucidBrot/cevi-versand cevi-versand] erstellt nach einmaligem einrichten mit minimalem manuellen Aufwand PDFs um Couverts für den Versand zu drucken. Dafür verwendet es auch die API. Unter anderem kann man damit:
 
Das Tool [https://github.com/lucidBrot/cevi-versand cevi-versand] erstellt nach einmaligem einrichten mit minimalem manuellen Aufwand PDFs um Couverts für den Versand zu drucken. Dafür verwendet es auch die API. Unter anderem kann man damit:
* Ein Cevi-Logo auf den Umschlag drucken.
+
 
* Personen die zusammen wohnen in ein gemeinsames Couvert bringen. Das bedeutet weniger Arbeit beim Verpacken.
+
*Ein Cevi-Logo auf den Umschlag drucken.
* Fehlerhafte Einträge in der DB finden - beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.
+
*Personen die zusammen wohnen in ein gemeinsames Couvert bringen. Das bedeutet weniger Arbeit beim Verpacken.
* Cevinamen und dazugehörige Stufennamen aufdrucken. Das vereinfacht das verteilen, wenn man nicht alle Empfänger gut kennt.
+
*Fehlerhafte Einträge in der DB finden - beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.
* Aufdrucken wie viele Leiter/Teilnehmer im Umschlag sind. Das vereinfacht das verpacken, wenn man nicht alle Empfänger gut kennt.
+
*Cevinamen und dazugehörige Stufennamen aufdrucken. Das vereinfacht das verteilen, wenn man nicht alle Empfänger gut kennt.
 +
*Aufdrucken wie viele Leiter/Teilnehmer im Umschlag sind. Das vereinfacht das verpacken, wenn man nicht alle Empfänger gut kennt.
 +
 
 
[https://github.com/lucidBrot/cevi-versand cevi-versand] ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :)
 
[https://github.com/lucidBrot/cevi-versand cevi-versand] ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :)
===Ablauf einer Abfrage===
+
====Ablauf einer Abfrage====
  
 
#Login-Anfrage mit Email und Passwort senden
 
#Login-Anfrage mit Email und Passwort senden
Zeile 23: Zeile 41:
 
'''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.
 
'''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===
+
====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.
 
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====
+
=====Beispiele=====
 
'''Python:'''
 
'''Python:'''
 
<syntaxhighlight lang="python" line="line">
 
<syntaxhighlight lang="python" line="line">
Zeile 40: Zeile 58:
 
</syntaxhighlight>
 
</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.
 
'''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===
+
====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:
 
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"
 
{| class="wikitable"
Zeile 53: Zeile 71:
 
|}
 
|}
 
Als Parameter müssen wie beim Login <code>person[email]</code> und <code>person[password]</code> übergeben werden.
 
Als Parameter müssen wie beim Login <code>person[email]</code> und <code>person[password]</code> übergeben werden.
===Daten abfragen===
+
====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>
 
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:
 
Bei jeder Abfrage müssen zudem die Email-Adresse und das <code>user token</code> mitgesendet werden. Dazu bestehen zwei Möglichkeiten:
Zeile 61: Zeile 79:
  
 
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>.
 
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====
+
=====Beispiele=====
 
Normale Abfrage mit Python:
 
Normale Abfrage mit Python:
 
<syntaxhighlight lang="python" line="1">
 
<syntaxhighlight lang="python" line="1">
Zeile 86: Zeile 104:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
Anfrage mit Rollenauswahl mit Python:
 
Anfrage mit Rollenauswahl mit Python:
<syntaxhighlight lang="python" line="line">
+
<syntaxhighlight lang="python" line="1">
 
# nach Login, Variable token ist definiert
 
# nach Login, Variable token ist definiert
 
# gewünscht ist eine Sortierung nach Rollen und eine Auswahl (nur AL)
 
# gewünscht ist eine Sortierung nach Rollen und eine Auswahl (nur AL)
Zeile 94: Zeile 112:
 
data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.
 
data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.
 
</syntaxhighlight>
 
</syntaxhighlight>
===Endpunkte===
+
====Endpunkte====
 
{| class="wikitable"
 
{| class="wikitable"
 
!Endpunkt
 
!Endpunkt
 
!URL
 
!URL
!Beispiel (gid=1, pid=2)
+
!Beispiel (gid=1, pid=2, eid=3)
 
|-
 
|-
 
|Gruppen <code><gid></code>
 
|Gruppen <code><gid></code>
Zeile 111: Zeile 129:
 
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people/<pid>.json
 
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/people/<pid>.json
 
|<nowiki>https://db.cevi.ch/groups/1/people/2.json</nowiki>
 
|<nowiki>https://db.cevi.ch/groups/1/people/2.json</nowiki>
 +
|-
 +
|Events <code><eid></code>
 +
|<nowiki>https://db.cevi.ch/groups/</nowiki><gid>/events/<eid>/participations.json
 +
|<nowiki>https://db.cevi.ch/groups/1/events/3/participations.json</nowiki>
 
|}
 
|}
 +
Über den Events-Endpunkt können auch die Fragen, welche beim Anlass/Kurs erfasst sind, abgefragt werden. Diese sind im json zu finden.
 +
 
'''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.
 
'''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]]
 
[[Kategorie:CeviDB]]

Aktuelle Version vom 26. Februar 2021, 08:54 Uhr

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. Es gibt zwei Methoden, um Daten automatisiert auszulesen. Beide sind hier kurz erklärt.

User-Tokens

Dies ist ein Token, dass persönlich ist. Das heisst, es hat den gleichen Zugriff (lesen) wie der Ersteller. Auf lange Sicht wird diese Art eventuell auch wieder abgeschaltet.

Service-Tokens

Dies ist die neue Version der Abfragen. Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "ofizielle" Dokumentation auf Github: [1]. Für die Service Tokens kann ganz genau eingestellt werden, welche Berechtigungen sie haben. Sie können auf einer Gruppe erstellt werden (auf der Gruppe im Menu oben auf "Api-Keys", https://db.cevi.ch/groups/GRUPPE/service_tokens)


API

Die API wird von beiden, User-Tokens und Service-Tokens verwendet. Die offizielle Dokumentation finded ihr auch auf Github: [2]. Untenstehend sind doch noch einige kurze Anleitungen und Informationen gesammelt. Sie sind für die User-Tokens geschrieben. Für den Gebrauch von Service-Tokens ändern sich die Endpunkte nicht, nur die Parameter ändern sich von

user_email=info@cevi.ch&user_token=AABBCC

hin zu

token=DDEEFF

Allgemeine Hinweise

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.

Tools
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 Github heruntergeladen werden.

Couvertgenerator

Das Tool cevi-versand erstellt nach einmaligem einrichten mit minimalem manuellen Aufwand PDFs um Couverts für den Versand zu drucken. Dafür verwendet es auch die API. Unter anderem kann man damit:

  • Ein Cevi-Logo auf den Umschlag drucken.
  • Personen die zusammen wohnen in ein gemeinsames Couvert bringen. Das bedeutet weniger Arbeit beim Verpacken.
  • Fehlerhafte Einträge in der DB finden - beispielsweise warnt das Tool, wenn jemand in keiner Ortschaft wohnt.
  • Cevinamen und dazugehörige Stufennamen aufdrucken. Das vereinfacht das verteilen, wenn man nicht alle Empfänger gut kennt.
  • Aufdrucken wie viele Leiter/Teilnehmer im Umschlag sind. Das vereinfacht das verpacken, wenn man nicht alle Empfänger gut kennt.

cevi-versand ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :)

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 ein 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

Python:

1 import requests
2 email = "ceviname@cevi.ch"
3 passwort = "123456"
4 res = requests.post('https://db.cevi.ch/users/sign_in.json?person[email]='+email+'&person[password]='+passwort)
5 token = res.json()["people"][0]["authentication_token"]

Shell:

1 wget --post-data 'person[email]=ceviname@cevi.ch&person[password]=123456' -o result.json https://db.cevi.ch/users/sign_in.json
2 cat result.json

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 user token 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:

Request Typ URL
post https://db.cevi.ch/users/token.json
delete https://db.cevi.ch/users/token.json

Als Parameter müssen wie beim Login person[email] und person[password] ü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 .json Bei jeder Abfrage müssen zudem die Email-Adresse und das user token mitgesendet werden. Dazu bestehen zwei Möglichkeiten:

  • als URL-Parameter: .json?user_email=ceviname@cevi.ch&user_token=123456
  • als Headers: X-User-Email: ceviname@cevi.ch, X-User-Token: 123456 und Accept: application/json

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 .json.

Beispiele

Normale Abfrage mit Python:

1 import requests
2 # vor diesem Teil muss natürlich das Token ausgelesen und gespeichert werden
3 email = "ceviname@cevi.ch"
4 token= "1a2b3c"
5 res = requests.post('https://db.cevi.ch/groups/5/people.json?user_email='+email+'&user_token='+token)
6 data = res.json()["people"]

Normale Anfrage mit der Shell:

1 wget --header "X-User-Email: ceviname@cevi.ch" --header "X-User-Token: 1a2b3c" \
2   --header "Accept: application/json" https://db.cevi.ch/groups/5/people.json -O people.json
3 cat people.json

Anfrage mit Sortierung mit Python:

1 # nach Login, Variable token ist definiert
2 # gewünscht ist eine Sortierung nach Rollen
3 # 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.
4 res = requests.get('https://db.cevi.ch/groups/5/people.json?sort=roles&sort_dir=asc&user_email=ceviname@cevi.ch&user_token='+token)
5 data = res.json()['people']

Anfrage mit Rollenauswahl mit Python:

1 # nach Login, Variable token ist definiert
2 # gewünscht ist eine Sortierung nach Rollen und eine Auswahl (nur AL)
3 # der Teil sort=roles&sort_dir=asc sortiert nun nach den Rollen.
4 # der Teil filters[role][finish_at]=&filters[role][role_type_ids]=35&filters[role][start_at]=&name=&range=deep grenzt die Rollen ein.
5 res = requests.get('https://db.cevi.ch/groups/5/people.json?filters[role][finish_at]=&filters[role][role_type_ids]=35&filters[role][start_at]=&name=&range=deep&sort=roles&sort_dir=asc&user_email=ceviname@cevi.ch&user_token='+token)
6 data = res.json()['people'] #ist hier leer, da auf der Geschäfsstelle (Gruppe 5) keine Abteilungsleiter erfasst sind.

Endpunkte

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

Über den Events-Endpunkt können auch die Fragen, welche beim Anlass/Kurs erfasst sind, abgefragt werden. Diese sind im json zu finden.

Hinweis: Wird versucht ohne Gruppen-Angabe auf eine Person zuzugreifen (https://db.cevi.ch/people/<pid>.json) so wird die Anfrage auf die Hauptgruppe 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.