Was Sie brauchen
Für die Schnittstelle brauchen Sie ein Konto. Ohne Anmeldung antwortet sie mit «401 Anmeldung erforderlich». Ausgenommen sind nur die Abfragen, die die Seiten von Frag den Bund selbst für Besucherinnen und Besucher machen, zum Beispiel die Suche nach Behörden im Anfrageformular.
Melden Sie sich an oder erstellen Sie ein Konto.
Dokumentation
Alle Adressen, Felder und Filter sind in der interaktiven Dokumentation beschrieben (nur mit Konto sichtbar). Das Schema (OpenAPI) können Sie für Ihr Werkzeug herunterladen. Die Schnittstelle liegt unter /api/v1/ und antwortet mit JSON; für Listen gibt es auch ?format=csv.
Zugang für Programme
Programme melden sich nicht mit Ihrem Passwort an, sondern mit einem Zugangsschlüssel (Token) über OAuth 2.0 (Authorization Code). So gehen Sie vor:
-
Registrieren Sie eine App (Konto, Einstellungen, Entwickler). Sie erhalten eine Client-ID. Redirect-Adressen müssen mit
https://beginnen. Programme in Browser oder Telefon sind öffentliche Apps und müssen PKCE verwenden. - Die Person, deren Konto die App nutzt, öffnet die Anmeldeadresse und erlaubt den Zugriff. Das kann auch Sie selbst sein.
- Die App tauscht den Code gegen ein Token. Das Token gilt 60 Minuten; mit dem Erneuerungs-Token (gültig 30 Tage) holt die App ein neues.
# 1. Diese Adresse im Browser öffnen. Die Person meldet sich an und erlaubt den Zugriff.
https://fragdenbund.ch/account/authorize/?response_type=code&client_id=CLIENT_ID&redirect_uri=https://app.example.org/callback&scope=read:request&code_challenge=CHALLENGE&code_challenge_method=S256
# 2. Den Code, der an Ihrer Weiterleitungsadresse ankommt, gegen ein Token tauschen.
curl -X POST https://fragdenbund.ch/account/token/ \
-d grant_type=authorization_code -d code=CODE -d client_id=CLIENT_ID \
-d redirect_uri=https://app.example.org/callback -d code_verifier=VERIFIER
# 3. Die API mit dem Token aufrufen.
curl -H "Authorization: Bearer ACCESS_TOKEN" "https://fragdenbund.ch/api/v1/request/?format=json"
Wer Zugriff gegeben hat, kann ihn jederzeit unter Einstellungen, Apps mit Zugriff wieder entziehen. Eine App kann nur das tun, was bei der Erlaubnis angezeigt wurde:
| Berechtigung | Erlaubt der App |
|---|---|
read:user
|
Kann Sie als Nutzer:in auf Frag den Bund identifizieren |
read:profile
|
Kann Ihre Profilinformationen sehen |
read:email
|
Kann Ihre E-Mail-Adresse sehen |
read:request
|
Kann Ihre (privaten) Anfragen sehen |
make:request
|
Kann Anfragen in Ihrem Namen stellen |
write:request
|
Anfragen bearbeiten |
write:message
|
Nachrichten hinzufügen und bearbeiten |
write:attachment
|
Anhänge hinzufügen und bearbeiten |
follow:request
|
Folge/Entfolge Anfragen |
read:document
|
Kann Ihre (privaten) Dokumente sehen |
Nutzungsgrenzen
Damit die Seite für alle schnell bleibt, gelten Grenzen pro Minute:
- Mit Konto: 300 Aufrufe.
- Suchen (Behörden, Anfragen, Textsuche): 60 Aufrufe.
- Ohne Konto, bei den wenigen offenen Abfragen: 120 Aufrufe.
Wird eine Grenze erreicht, antwortet die Schnittstelle mit «429» und nennt in Retry-After, wie viele Sekunden Sie warten sollen. Bitte bauen Sie das in Ihr Programm ein.
Was Sie nicht sehen
Die Schnittstelle zeigt dieselben Daten wie die Website. Nicht öffentliche Anfragen, Antworten, die noch nicht freigegeben sind, Namen von Anfragenden, die ihn nicht veröffentlichen, und E-Mail-Adressen von Behörden, die wir nicht anzeigen, fehlen auch hier.
Regeln
Es gelten die Nutzungsbedingungen, im Besonderen der Abschnitt zur Schnittstelle, und die Datenschutzerklärung. Wer die Grenzen umgeht oder Daten Dritter missbraucht, kann gesperrt werden.
Fragen und Fehler: info@fragdenbund.ch