REST-API

Unter /api/v1 stellt die Anwendung eine Schnittstelle bereit, mit der eigene Werkzeuge auf die Vereinsdaten zugreifen: die Vereinswebsite, ein Anmeldetool, eine Auswertung, eine Automatisierung.

Diese Referenz beschreibt sie vollständig. Wie der Zugang in der Anwendung beantragt und verwaltet wird, steht im Handbuch unter Einstellungen → Schnittstelle.

Basisadresse	https://<deine-domain>/api/v1
Beschreibung	GET /api/v1/openapi.json (OpenAPI 3.1, braucht ebenfalls einen Schlüssel)
Umfang	224 Endpunkte in 21 Bereichen
Anmeldung	Authorization: Bearer mv_…
Format	JSON (einige Endpunkte liefern eine Datei)

Schnellstart

1. Zugang freischalten lassen. Unter Einstellungen → API beantragen; die Instanz-Verwaltung gibt frei. Ohne Freischaltung antwortet jeder Aufruf mit 404 und dem Code api_not_enabled.

2. Bereiche freigeben. Ab Werk steht jeder Bereich auf aus. Erst was der Verein freigibt, kann ein Schlüssel überhaupt dürfen.

3. Schlüssel erzeugen. Unter Einstellungen → API → Zugangsschlüssel. Der Klartext wird genau einmal angezeigt.

4. Prüfen, ob alles sitzt:

curl -H "Authorization: Bearer mv_a1b2c3d4_…" \
  https://deine-domain.de/api/v1/me

{
  "data": {
    "token": { "id": "…", "name": "Website", "expires_at": "2027-02-14T00:00:00.000Z" },
    "scopes": ["veranstaltungen:read", "gruppen:read"],
    "rate_limit_per_minute": 120
  }
}

scopes nennt die tatsächlich wirksamen Bereiche – also das, was nach Abzug der vereinsweiten Obergrenze übrig bleibt. Steht dort weniger, als beim Anlegen angehakt wurde, fehlt die Freigabe des Bereichs, nicht das Recht am Schlüssel.

5. Loslegen:

curl -H "Authorization: Bearer mv_a1b2c3d4_…" \
  "https://deine-domain.de/api/v1/veranstaltungen?sort=start_at&per_page=10"

Aufbau dieser Referenz

Seite	Inhalt
Zugang & Schlüssel	Freischaltung, Schlüsselformat, Ablauf, Widerruf, /me
Bereiche (Scopes)	Die drei Ebenen der Berechtigung, alle Bereiche, bewusste Grenzen
Konventionen	Antwortform, Listen, Filter, Dateien, Zeitangaben, Limits, Protokoll
Fehler	Alle Codes mit Ursache und Abhilfe
Endpunkte	Alle 224 Endpunkte nach Bereich, mit Feldern und Beispielen
Rezepte	Fertige Abläufe für die häufigsten Aufgaben

Sechs Grundsätze

Wer die Schnittstelle anbindet, kommt schneller ans Ziel, wenn er diese sechs Punkte vorher kennt:

1. Dieselbe Fachlogik wie die Oberfläche. Die Endpunkte sind dünne Schichten über denselben Diensten. Ein über die API angelegtes Mitglied bekommt seine Mitgliedsnummer, eine Kündigung verschickt ihre Bestätigungsmail, eine Ausleihe wird auf Konflikte geprüft.
2. Feste Hülle. Einzelobjekt { "data": … }, Liste zusätzlich mit meta, Fehler { "error": { "code": …, "message": … } }. Codes sind englisch und stabil, Meldungen deutsch und für Menschen.
3. Deny by default. Kein Bereich ist ab Werk offen – auch keiner, der später dazukommt.
4. Alles Schreibende steht im Protokoll. Unter api:<Name des Schlüssels>, mit demselben Vorher/Nachher-Vergleich wie eine Änderung aus der Oberfläche.
5. Gefährliche Vorgänge bleiben in der Anwendung. Kontoauszug-Import, SEPA-Datei, Konten und Rollen, endgültiges Löschen. Das sind bewusste Grenzen, keine Lücken.
6. /api/v1 ist ein Versprechen. Felder können hinzukommen; was bestehende Aufrufe bräche, käme unter /api/v2.