Cevi.DB API: Unterschied zwischen den Versionen
Carbon (Diskussion | Beiträge) |
|||
(11 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
Zeile 1: | Zeile 1: | ||
− | Die | + | Die Cevi.DB bietet eine <abbr>API</abbr>, mit der Personen- und Gruppen-Daten aus der Datenbank ausgelesen werden können. Datenveränderungen sind über die API hingegen '''nicht''' möglich. |
− | === | + | ==OAuth Provider== |
− | Die Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet [http://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] als Datenformat | + | Die Cevi.DB kann als OAuth Provider genutzt werden. Dies benötigt allerdings eine Konfiguration seitens Cevi.DB Steuergruppe. Melde Dich dafür bei cevidb(at)cevi.ch. |
− | + | ||
− | + | ==API Nutzung== | |
− | + | Die REST-Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet [http://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] als Datenformat. Die offizielle Dokumentation findet ihr auch auf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md]. | |
− | |||
− | |||
− | + | '''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 cevidb(at)cevi.ch, wenn ihr ein Skript erstellt und ein <code>user token</code> hinterlegt. | |
− | |||
− | |||
− | |||
− | |||
− | + | ===Authentifizierung=== | |
− | === | + | Zur Nutzung der API ist ein Token notwendig. Momentan gibt es zwei Arten von Tokens. |
− | + | ====User-Tokens==== | |
− | + | '''============== !! User-Token wurden mit dem Update vom 2024-01-09 deaktiviert!! ============== ''' | |
− | |||
− | |||
− | + | Dies ist ein persönliches Token. Das heisst, es hat den gleichen Zugriff (lesen) wie der Ersteller. Auf lange Sicht wird diese Art eventuell auch wieder abgeschaltet. | |
− | + | Das Token erhältst du mit folgendem Request:<syntaxhighlight lang="bash" line="1"> | |
− | + | wget -O- https://db.cevi.ch/users/sign_in.json --post-data 'person[email]=<YOURUSERNAME>&person[password]=<YOURPASSWORD>' | |
− | |||
− | |||
− | <syntaxhighlight lang=" | ||
− | |||
− | |||
− | |||
− | |||
− | |||
</syntaxhighlight> | </syntaxhighlight> | ||
− | + | Das User-Token ist im Property "authentication_token" im JSON der Antwort enthalten. Das Token bleibt konstant und kann daher auch über längere Zeit verwendet werden. | |
− | < | + | |
− | + | Das Token muss bei den Abfragen entweder als Query Parameter (<code><URL>?user_email=<YOURUSERNAME>&user_token=<YOURTOKEN></code>) oder im HTTP Header (bevorzugt da sicherer, <code>X-User-Email: ceviname@cevi.ch, X-User-Token: 123456</code>) übergeben werden. | |
− | + | ||
− | </ | + | ====Service-Tokens (empfohlen)==== |
− | + | Dies ist die neue Art der Authentifizierung. Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "offizielle" Dokumentation auf Github: [https://github.com/hitobito/hitobito/blob/master/doc/development/07_service_accounts.md]. | |
− | + | ||
− | Das <code> | + | Das Token kann jeweils von den Abteilungsleitern auf der Ortsgruppe im Reiter Einstellungen mit der Schaltfläche "API-Keys" erstellt werden (<nowiki>https://db.cevi.ch/groups/GRUPPENID/service_tokens</nowiki>). Dabei kann sowohl der Scope (z. B. aktuelle Ebene oder auch darunterliegende) wie auch die Rechte (z. B. Gruppen lesen, Personen lesen, Anlässe lesen, ...) definiert werden. |
+ | |||
+ | Das Token muss bei den Abfragen jeweils wie folgt übergeben werden: <code><URL>?token=<YOURTOKEN></code> | ||
+ | ===Endpunkte=== | ||
{| class="wikitable" | {| class="wikitable" | ||
− | ! | + | !Endpunkt |
!URL | !URL | ||
+ | !Beispiel (gid=1, pid=2, eid=3) | ||
+ | !Hinweise | ||
+ | |- | ||
+ | |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> |
− | |https://db.cevi.ch/ | + | |<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/groups/1/people/2.json</nowiki> | ||
+ | |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. | ||
+ | |- | ||
+ | |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. | ||
|- | |- | ||
− | | | + | |User Token verwalten |
|https://db.cevi.ch/users/token.json | |https://db.cevi.ch/users/token.json | ||
+ | | | ||
+ | |Bei einem post request wird ein neues erstellt, bei einem delete Request wird das bestehende gelöscht. Als Parameter müssen wie beim Login <code>person[email]</code> und <code>person[password]</code> übergeben werden. | ||
|} | |} | ||
− | + | ===Beispiele (mit User Tokens)=== | |
− | ===Daten abfragen=== | + | |
+ | ====User Token ermitteln==== | ||
+ | Python:<syntaxhighlight lang="python" line="line"> | ||
+ | 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. | ||
+ | |||
+ | ====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 62: | Zeile 80: | ||
*als Headers: <code>X-User-Email: ceviname@cevi.ch, X-User-Token: 123456</code> und <code>Accept: application/json</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” | + | Weiter können weitere GET-Parameter (analog zur “richtigen” Cevi.DB) angehängt werden. Am besten führt man das Gewünschte in der Cevi.DB aus (zum Beispiel Sortieren nach Rollen) und kopiert die URL, ändert die Endung zu <code>.json</code>. |
− | + | ||
Normale Abfrage mit Python: | Normale Abfrage mit Python: | ||
<syntaxhighlight lang="python" line="1"> | <syntaxhighlight lang="python" line="1"> | ||
Zeile 88: | Zeile 106: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Anfrage mit Rollenauswahl mit Python: | Anfrage mit Rollenauswahl mit Python: | ||
− | <syntaxhighlight lang="python" 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 96: | Zeile 114: | ||
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> | ||
− | === | + | ==Tools== |
− | + | ===Spender-Tool des RV (cevidbtool)=== | |
− | + | 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 (cevi-versand)=== | |
− | + | 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. | |
− | + | *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. | |
− | + | ||
− | + | [https://github.com/lucidBrot/cevi-versand cevi-versand] ist open-source und gratis zu benutzen, aber Spenden werden geschätzt :) | |
− | + | [[Kategorie:Cevi.DB]] | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | [[Kategorie: |
Aktuelle Version vom 10. Januar 2024, 05:50 Uhr
Die Cevi.DB bietet eine API, mit der Personen- und Gruppen-Daten aus der Datenbank ausgelesen werden können. Datenveränderungen sind über die API hingegen nicht möglich.
OAuth Provider
Die Cevi.DB kann als OAuth Provider genutzt werden. Dies benötigt allerdings eine Konfiguration seitens Cevi.DB Steuergruppe. Melde Dich dafür bei cevidb(at)cevi.ch.
API Nutzung
Die REST-Schnittstelle wird über POST- und GET-Anfragen angesteuert und verwendet JSON als Datenformat. Die offizielle Dokumentation findet ihr auch auf Github: [1].
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(at)cevi.ch, wenn ihr ein Skript erstellt und ein user token
hinterlegt.
Authentifizierung
Zur Nutzung der API ist ein Token notwendig. Momentan gibt es zwei Arten von Tokens.
User-Tokens
============== !! User-Token wurden mit dem Update vom 2024-01-09 deaktiviert!! ==============
Dies ist ein persönliches Token. Das heisst, es hat den gleichen Zugriff (lesen) wie der Ersteller. Auf lange Sicht wird diese Art eventuell auch wieder abgeschaltet.
Das Token erhältst du mit folgendem Request:
1 wget -O- https://db.cevi.ch/users/sign_in.json --post-data 'person[email]=<YOURUSERNAME>&person[password]=<YOURPASSWORD>'
Das User-Token ist im Property "authentication_token" im JSON der Antwort enthalten. Das Token bleibt konstant und kann daher auch über längere Zeit verwendet werden.
Das Token muss bei den Abfragen entweder als Query Parameter (<URL>?user_email=<YOURUSERNAME>&user_token=<YOURTOKEN>
) oder im HTTP Header (bevorzugt da sicherer, X-User-Email: ceviname@cevi.ch, X-User-Token: 123456
) übergeben werden.
Service-Tokens (empfohlen)
Dies ist die neue Art der Authentifizierung. Sie ändern momentan recht schnell, aus diesem Grund verweisen wir hier nur auf die "offizielle" Dokumentation auf Github: [2].
Das Token kann jeweils von den Abteilungsleitern auf der Ortsgruppe im Reiter Einstellungen mit der Schaltfläche "API-Keys" erstellt werden (https://db.cevi.ch/groups/GRUPPENID/service_tokens). Dabei kann sowohl der Scope (z. B. aktuelle Ebene oder auch darunterliegende) wie auch die Rechte (z. B. Gruppen lesen, Personen lesen, Anlässe lesen, ...) definiert werden.
Das Token muss bei den Abfragen jeweils wie folgt übergeben werden: <URL>?token=<YOURTOKEN>
Endpunkte
Endpunkt | URL | Beispiel (gid=1, pid=2, eid=3) | Hinweise |
---|---|---|---|
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 | 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.
|
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. |
User Token verwalten | https://db.cevi.ch/users/token.json | Bei einem post request wird ein neues erstellt, bei einem delete Request wird das bestehende gelöscht. Als Parameter müssen wie beim Login person[email] und person[password] übergeben werden.
|
Beispiele (mit User Tokens)
User Token ermitteln
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"]
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.
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
undAccept: application/json
Weiter können weitere GET-Parameter (analog zur “richtigen” Cevi.DB) angehängt werden. Am besten führt man das Gewünschte in der Cevi.DB aus (zum Beispiel Sortieren nach Rollen) und kopiert die URL, ändert die Endung zu .json
.
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.
Tools
Spender-Tool des RV (cevidbtool)
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 (cevi-versand)
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 :)