HTTP-Schnittstelle
Auf dieser Seite

HTTP-Schnittstelle

Eingebettete Hilfe

GET /hilfe liefert den Hilfeeinstieg als vollständig gerendertes HTML. GET /hilfe/{thema} öffnet eine Anleitung, beispielsweise mitglieder, gaeste, oeffentlichkeit, leitung, terminpflege, gruppenchats, administration, serverbetrieb oder fragen. Die Referenzseiten sind ebenfalls innerhalb der Hilfe verlinkt. Unbekannte Themen liefern eine lesbare 404-Seite. Styles und die optionale Druckfunktion liegen unter /help.css und /help.js.

q durchsucht ausschließlich die eingebetteten Anleitungstexte, einschließlich Tabellen und Codebeispielen. Die Suche verwendet höchstens 120 Zeichen und unterstützt auch Umschreibungen wie geraet für Gerät. fuer wählt eine bekannte Nutzergruppe für die Empfehlungen; ohne diesen Hinweis wird die Mitgliedersitzung berücksichtigt. Der Parameter vergibt keine Anwendungsrechte. lang=en ergänzt den Hinweis, dass die Anleitungen auf Deutsch vorliegen. Kanonische Hilfeadressen enthalten keine Such- oder Kontextparameter.

Die Hilfetexte enthalten allgemeine Anleitungen und erfordern keine Mitgliedersitzung. Der konfigurierte zusätzliche Pfadschutz gilt weiterhin. Die Hilfeseiten starten den Anwendungsklienten nicht; Lesen, Suche und Navigation funktionieren ohne JavaScript. Links aus der Anwendung öffnen separat und enthalten keine persönlichen Freischalt-, Gast- oder Abotokens.

Anwendungsschnittstelle

Für konfigurierte Pfade kann zusätzlich HTTP Basic Authentication erforderlich sein; Pfadumfang und Konfiguration stehen in Betrieb. Alle JSON-Endpunkte liegen auf derselben konfigurierten Browseradresse. Schreibende Aufrufe benötigen exakt passenden Origin und X-CSRF-Token aus bootstrap. Ausnahmen vom CSRF-Token sind setup, login, access/redeem und der exakt abgegrenzte Gast-Stimmendpunkt; der Origin bleibt erforderlich. Gäste verwenden ein abstimmungsspezifisches Zugriffstoken im Header X-Poll-Invite (alternativ Authorization: Bearer …). Eine Mitgliedersitzung allein berechtigt nicht zum Gastzugriff. Sitzung als HttpOnly/SameSite-Lax-Cookie, unter HTTPS Secure. Keine fremden Antworten in Terminlisten oder persönlichen Abos.

Methode / Pfad Inhalt
GET /api/bootstrap Sichtbare Person, Gruppen, Berechtigungen, CSRF, Abgleichintervall und Kalenderstatus ohne Quelladressen
POST /api/setup token, name, orgName optional, password; erste Administration
POST /api/login password; ausschließlich Administration
POST /api/logout aktuelles Gerät abmelden
GET /api/access?token=… einmaligen Zugang prüfen, verbraucht ihn nicht
POST /api/access/redeem token; Gerät freischalten, Zugang verbrauchen
GET /api/polls Sichtbare interne Abstimmungen und eigene Stimmen; Ergebnisse nur für Berechtigte
POST /api/polls/{id}/vote optionId und vote (yes, no, maybe, leer zum Zurücknehmen)
POST /api/polls/{id}/votes votes als Objekt aus Vorschlags-ID und Stimme; atomare Teilaktualisierung
POST /api/polls title, audience, options mit start/end; optional description, location, deadline; Administration oder zuständige Leitung
POST /api/polls/{id}/close Abstimmung ohne Auswahl schließen
POST /api/polls/{id}/finalize optionId; Vorschlag festlegen und Abstimmung schließen
POST /api/polls/{id}/publish optionId als erwartete Auswahl, calendarId optional; festgelegten Vorschlag atomar in lokalen Kalender derselben Zielgruppe übernehmen; gibt eventId und calendarId zurück
GET /api/polls/{id}/results.csv Zusammengefasste Ergebnisse pro Vorschlag, nur zuständige Leitung/Administration; keine Namen oder Einzelstimmen
POST /api/polls/{id}/reopen Vor einer Kalenderübernahme wieder öffnen; Auswahl und Antwortfrist werden aufgehoben
POST /api/polls/{id}/guests name; persönliche Gasteinladung erzeugen, gibt id, url und expires zurück
POST /api/polls/{id}/guests/{guestID}/invite Gastlink ersetzen; Stimmen bleiben erhalten
DELETE /api/polls/{id}/guests/{guestID}/invite Gastlink sperren; Stimmen bleiben erhalten
GET /api/poll-guest Nur die eingeladene Abstimmung und eigene Gaststimmen; Token erforderlich
POST /api/poll-guest/votes votes als Objekt; Token und Origin erforderlich, keine Mitgliedersitzung/CSRF-Token
POST /api/admin/polls Kompatibler Endpunkt zum Anlegen einer Abstimmung
POST /api/admin/polls/{id}/close Kompatibler Endpunkt zum Schließen
DELETE /api/admin/polls/{id} Geschlossene Abstimmung und Stimmen entfernen, nur Administration; ein übernommener Kalendertermin bleibt bestehen
GET /api/events sichtbare Termine mit ausschließlich eigener Antwort
POST /api/events Lokalen Termin anlegen: calendarId, title, description, location, allDay, zone und Zeitraum; optional recurrence für eine Serie; zuständige Leitung/Administration, gibt id und bei Serien seriesId zurück
GET /api/export/events.{json,csv,jcal,xcal,rss} sichtbare Termine für das angemeldete Mitglied, ohne Antworten
GET /api/events/{id} sichtbarer Termin
POST /api/events/{id}/edit Vollständige Termindaten und bisheriges updated; nur lokale Termine mit Leitungsrecht, Kalender und Status bleiben fest; gibt id zurück
POST /api/events/{id}/response status yes/no, comment, revision
POST /api/events/{id}/status status confirmed/cancelled, revision; nur zuständige Leitung/Administration bei lokalen Terminen, bestehende Antworten bleiben erhalten
GET /api/event-series/{id} Serienvorgaben, recurrence, updated, Status und Umfang; nur zuständige Leitung/Administration
POST /api/event-series/{id}/edit Vollständige lokale Termindaten, recurrence, updated; resetExceptions optional false; gesamte Serie atomar ändern
POST /api/event-series/{id}/status status confirmed/cancelled, updated; Status aller aktuellen Vorkommen setzen, einschließlich individueller Statusausnahmen
GET /api/events/{id}/attendance Rückmeldungen, nur mit Leitungsrecht der Zielgruppe
GET /api/events/{id}/attendance.csv dieselben Daten als formelsicheres CSV
GET /api/admin Kalenderquellen, Mitglieder, Gruppen und Einstellungen, nur Administration
POST /api/admin/calendars id optional, name, url, audience, rsvp, external, local; lokale Kalender haben local true, leere url und external false
DELETE /api/admin/calendars/{id} leeren Kalender löschen; gefüllten deaktivieren
POST /api/admin/calendars/{id}/sync Feedkalender manuell abgleichen; lokale Kalender werden nicht abgerufen
POST /api/admin/members id optional, name, groups, leadGroups, disabled
POST /api/admin/members/{id}/access einmaligen Einrichtungslink erzeugen
POST /api/admin/members/{id}/revoke Geräte, offene Links und Abo sperren
POST /api/admin/groups id optional, name; Gruppe anlegen oder umbenennen
DELETE /api/admin/groups/{id} nicht verwendete Gruppe löschen
POST /api/admin/path-auth Pfadschutz aktivieren, ändern oder deaktivieren; ohne Klartext-Rückgabe
POST /api/admin/settings optionale Felder orgName, accentColor (#RRGGBB oder leer für Standard), deadlineHours von 0 bis 720, syncIntervalMinutes von 1 bis 1440, syncPastDays von 1 bis 365, syncFutureMonths von 1 bis 60; fehlende Felder bleiben erhalten
GET /api/admin/backup vertrauliche vollständige JSON-Sicherung
POST /api/subscription persönliches Abo erzeugen/ersetzen; url und webcalURL einmalig zurück
GET /calendar/public.{ics,json,csv,jcal,xcal,rss} öffentliche Termine
GET /calendar/{token}.{ics,json,csv,jcal,xcal,rss} persönlich berechtigte Termine, keine Antworten
GET /healthz Prozess erreichbar

Zielgruppen: public für Öffentlichkeit, all für alle aktiven Mitglieder und die IDs der angelegten Gruppen. Jede Mitgliedschaft umfasst all. leadGroups vergibt Einsicht in Antworten gesondert zur Gruppenzugehörigkeit. Eine Antwort auf externe Termine ist nur eine interne Mitteilung.

API-Fehler enthalten JSON mit error: 400 bei ungültiger Eingabe, 401 bei fehlenden oder falschen Basic-Zugangsdaten für geschützte Pfade, 403 bei fehlender Berechtigung, ungültigem Origin oder CSRF-Token, 404 bei nicht sichtbaren Terminen oder ungültigen Links, 409 bei einem Konflikt, 429 bei zu vielen Anfragen und 503 bei Speicherfehlern. Der xCal- oder RSS-Export kann 422 zurückgeben, wenn gespeicherter Text nicht in XML 1.0 darstellbar ist. Ereignisse werden aus konfigurierten HTTPS- oder webcal-Feeds in ICS, jCal, xCal, RSS, JSON oder CSV sowie aus einem Teilumfang von Schema.org-JSON-LD übernommen; URL-Pfade und Query-Parameter dürfen ein Zugriffstoken enthalten. Lokale Termine entstehen über die Kalenderübernahme aus Abstimmungen oder die direkte Anlage. Sie können lokal bearbeitet, abgesagt und wieder aktiviert werden. Externe Feedtermine werden weiterhin beim Anbieter gepflegt; dessen Kalender wird nicht beschrieben.

Abstimmungen sind auf interne Zielgruppen begrenzt. Ergebnisse, Beteiligungszahlen und Gasteinladungen werden nur an zuständige Leitungen und Administration ausgegeben. Normale Mitglieder und Gäste erhalten nur ihre eigenen Stimmen. Antwortfristen und geschlossene Abstimmungen werden serverseitig geprüft.

GET /api/polls liefert zusätzlich canPublish, published und bei einem sichtbaren übernommenen Termin eventId sowie calendarEvent mit aktuellen Termindaten. Die ursprünglichen Optionen und Stimmen bleiben beim Bearbeiten des Kalendertermins unverändert. conflicts enthält je Vorschlags-ID höchstens fünf nach Zeit und ID sortierte Überschneidungen mit id, title, start, end und calendarName; conflictCounts enthält die Gesamtzahl. Berücksichtigt werden ausschließlich sichtbare, bestätigte und nicht ungeklärte Termine. Randberührung gilt nicht als Überschneidung. Hinweise fehlen bei bereits übernommenen sowie geschlossenen Abstimmungen ohne Auswahl. Gäste erhalten keine Konflikthinweise oder Kalendertermin-IDs. Der Status des eigenen übernommenen Termins wird als eventStatus auch im Gastzugang angezeigt, damit eine Absage erkennbar bleibt. calendarEvent enthält für Gäste ausschließlich title, location, start, end, allDay, zone und status; eine später geänderte Kalenderbeschreibung wird nicht freigegeben.

publish prüft Leitungsrecht und erwartete Auswahl innerhalb derselben Datenänderung. Ohne calendarId verwendet der Server deterministisch einen passenden aktiven lokalen Kalender oder legt Vereinstermine mit Rückmeldungen für dieselbe Zielgruppe an. Ein Feedkalender, eine andere Zielgruppe oder ein deaktivierter Kalender ist kein zulässiges Ziel. Wiederholte Aufrufe erzeugen keinen zweiten Termin. Stimmen werden nicht in verbindliche Rückmeldungen kopiert. Die übernommene Abstimmung kann nicht erneut geöffnet oder auf einen anderen Vorschlag festgelegt werden. Kalenderabos und Exporte enthalten den lokalen Termin über die üblichen Sichtbarkeitsregeln.

GET /api/events und die Detailantwort liefern local, canManageEvent und fromPoll (Verknüpfung mit einer noch vorhandenen Abstimmung). Bei lokalen Serien kommen seriesId, seriesIndex (ab null), seriesCount, seriesException, seriesRetired und canManageSeries hinzu. Aus dem Plan entfallene Vorkommen sind abgesagt und können nicht einzeln bearbeitet oder reaktiviert werden. Die Kalender in bootstrap enthalten canManageEvents. Ein Statuswechsel eines einzelnen Termins benötigt die aktuelle revision; bei veraltetem Stand antwortet der Server mit 409. Tatsächliche Statusänderungen erhöhen die Revision, damit bestehende Rückmeldungen eine erneute Bestätigung benötigen. Wiederholtes Setzen desselben Status mit aktueller Revision erhöht diese nicht erneut. Kalenderquelle und Sichtbarkeit bleiben bei gefüllten Kalendern geschützt, auch für lokale Quellen.

Lokale Termine anlegen und bearbeiten

POST /api/events verlangt einen vorhandenen, aktiven lokalen Kalender mit Leitungsrecht. Öffentliche Ziele benötigen zusätzlich confirmPublic: true. Neue Termine erhalten einen stabilen Quellschlüssel local:<ID> und Status confirmed. POST /api/events/{id}/edit erlaubt keine Änderung von Kalender, Quellschlüssel oder Status. Ein angenommener Body für einen Termin mit Uhrzeit sieht so aus:

{"calendarId":"lokaler-kalender","title":"Probe","description":"Instrumente mitbringen","location":"Vereinsheim","allDay":false,"zone":"Europe/Berlin","start":"2027-04-03T16:00:00Z","end":"2027-04-03T18:00:00Z"}

Beim Bearbeiten calendarId weglassen und den ursprünglichen Wert updated aus der Detailantwort mitsenden. Der Server vergleicht diesen Zeitstempel exakt. Ein veralteter Wert führt zu 409 und ändert keine Daten. Titel- und Beschreibungskorrekturen ändern updated, aber nicht die RSVP-Revision. Zeit, Ort, Ganztagsdarstellung oder die für ganztägige Daten relevante Zeitzone erhöhen zusätzlich die Revision. Eine unveränderte Speicherung behält beide Werte. Antworten, Nachrichten und Verknüpfungen mit Abstimmungen bleiben bestehen.

Für ganztägige Termine kann der Zeitraum als startDate und exklusives endDate im Format YYYY-MM-DD angegeben werden, beispielsweise allDay: true, zone: "Europe/Berlin", startDate: "2027-03-28", endDate: "2027-03-29". Der Server berechnet die lokalen Mitternachtszeitpunkte auch über Sommerzeitwechsel. Ein Datumsbody enthält keine zusätzlichen start/end-Zeitstempel. Alternativ werden für Ganztag konsistente Mitternachtszeitstempel akzeptiert. Zeitzonen müssen gültig und explizit sein; die serverabhängige Pseudozone Local wird abgelehnt.

Grenzen: Titel maximal 240 UTF-8-Bytes und nicht leer, Beschreibung maximal 32.000 UTF-8-Bytes, Ort maximal 1.000 UTF-8-Bytes, positive Dauer bis 366 × 24 Stunden. Das Anzeigen eines öffentlichen lokalen Kalenders erlaubt noch kein Schreiben; auch dort ist das gesonderte Leitungsrecht erforderlich.

Lokale Terminserien

Der optionale recurrence-Wert bei der Anlage beschreibt einen vollständigen endlichen Plan:

{"frequency":"weekly","interval":2,"weekdays":[1,3],"count":12}

frequency ist daily, weekly, monthly oder yearly. interval liegt zwischen 1 und 52. weekdays ist ausschließlich für wöchentliche Regeln zulässig und verwendet ISO-Wochentage von 1 (Montag) bis 7 (Sonntag), ohne Duplikate. Ohne Auswahl wird der Wochentag des ersten Termins verwendet; eine explizite Auswahl muss diesen Tag enthalten. Genau eine Endbedingung ist erforderlich: count von 1 bis 200 oder until als einschließlich geltendes Kalenderdatum YYYY-MM-DD in der Serienzeitzone. until begrenzt den Starttag eines Vorkommens; dessen Ende kann später liegen. Der Plan darf höchstens fünf Kalenderjahre umfassen und 200 tatsächliche Vorkommen erzeugen. Ein überschrittener Plan wird abgewiesen und nicht gekürzt.

Die Wiederholung erhält die lokale Uhrzeit der Serienzeitzone. Nicht existierende lokale Uhrzeiten und fehlende Monatstage werden übersprungen. count zählt gültige Vorkommen. Monatlich wird der Tag des ersten Termins verwendet, jährlich dessen Monat und Tag. Ganztägige Serien behalten ihre Dauer in Kalendertagen; zeitgebundene Serien ihre ursprüngliche verstrichene Dauer. Die Anlage erzeugt Definition und Vorkommen atomar, mit stabilen Termin-IDs pro Serienposition. Antworten bleiben an das jeweilige Vorkommen gebunden.

GET /api/event-series/{id} benötigt Leitungsrecht und liefert die Vorgaben des ersten Termins mit recurrence, updated, status, occurrenceCount, exceptionCount, retiredCount und canManage. Das Bearbeiten verwendet dieselben Metadaten und Zeitraumfelder wie lokale Einzeltermine, zusätzlich recurrence und den exakten Serienzeitstempel updated. Kalender und Status bleiben beim Bearbeiten fest. Für Uhrzeitfelder in der gespeicherten Serienzeitzone sind startLocal und endLocal im Format YYYY-MM-DDTHH:mm möglich. Je Endpunkt darf nur eine Darstellung verwendet werden, also beispielsweise start oder startLocal. So kann ein unveränderter Start seinen exakten UTC-Zeitstempel behalten, während ein geändertes Ende als lokale Uhrzeit eingegeben wird. Ganztägige Daten verwenden weiterhin startDate und exklusives endDate.

Einzeländerungen oder Einzelabsagen markieren das Vorkommen als Ausnahme und ändern den Serienzeitstempel. Dadurch schlägt ein parallel geöffneter veralteter Serienentwurf mit 409 fehl. Ganze Serienänderungen erhalten Ausnahmen standardmäßig. resetExceptions: true übernimmt für sie wieder die Serienvorgaben einschließlich Status. Bei Verkürzung bleiben entfallende Positionen mit stabiler ID als abgesagte seriesRetired-Termine erhalten. Bei Verlängerung werden vorhandene Positionen wiederverwendet; zusätzliche beginnen ohne Antworten. Tatsächliche Zeit-, Orts- oder Statusänderungen erhöhen die Revision des betroffenen Vorkommens, Textkorrekturen allein nicht. Eine unveränderte Speicherung erhöht keine Zeitstempel oder Revisionen.

Die Statusaktion für eine ganze Serie verwendet updated als Konkurrenzschutz und setzt den Status aller nicht entfallenen Vorkommen, auch von Ausnahmen. Sie verändert deren sonstige Metadaten nicht. Eine Reaktivierung kann damit individuelle Absagen aufheben; aus dem Plan entfallene Vorkommen bleiben abgesagt. Alle Serienoperationen gelten auch für vergangene Positionen. Persönliche Abos und die bestehenden Exporte enthalten die einzelnen Vorkommen und deren Absagestatus, ohne Antworten oder Serienverwaltungsrechte freizugeben.

Details zum JSON- und CSV-Schema stehen unter Terminformate.

Pfadschutz konfigurieren

POST /api/admin/path-auth benötigt eine Administrationssitzung, Origin und CSRF-Token. Beispiel für den Body:

{"enabled": true, "paths": ["/api/admin", "/calendar"], "username": "verein", "password": "ein-langes-individuelles-passwort"}

Beim Ändern eines bestehenden Schutzes erhält ein leeres Passwort das bisherige Passwort. enabled: false entfernt den gespeicherten Schutz. Der tatsächliche Passwort-Hash wird in keiner Admin-Antwort ausgegeben; GET /api/admin liefert unter pathAuth nur Status, Pfade, Benutzernamen und hasPassword. Ein über Umgebungsvariablen vorgegebener Schutz hat Vorrang und kann nicht über diesen Endpunkt geändert werden. Pfade schützen nur die explizit angegebenen HTTP-Routen; Einzelheiten und Wiederherstellung stehen in Betrieb.

GET-Pfad Ziel
/t/{id} Einzeltermin, Sichtbarkeit wie bei /api/events/{id}
/a/{id} Mitgliederabstimmungen, scrollt zur gewählten sichtbaren Abstimmung
/g/{audience} Terminübersicht der Zielgruppe; public öffentlich, all alle Mitglieder, sonst Gruppen-ID
/ Alle für die aktuelle Person sichtbaren Termine

Diese Adressen enthalten keine Zugriffstokens und umgehen weder Mitgliedsrechte noch zusätzlichen Pfadschutz. Das Frontend filtert Gruppenübersichten ausschließlich aus bereits serverseitig freigegebenen Terminen. Der Server liefert Open-Graph-Metadaten und kanonische URLs ohne Abfrageparameter. Termindetails werden nur für anonym sichtbare, aktive Kalender ausgegeben. Interne Ziele erhalten allgemeine Metadaten und noindex,nofollow; auch eine Verwaltungssitzung erweitert diese Vorschau nicht.

Der browserseitige Nachrichtendialog verwendet ausschließlich ausgewählte Terminangaben und gewöhnliche Links. Es gibt keinen Versandendpunkt und keine Verbindung zu einem bestimmten Chatdienst. Ein vorgemerktes geschütztes Ziel liegt für höchstens 30 Minuten im sessionStorage des Tabs. Nur lokale Termin-, Abstimmungs- und Gruppenpfade sowie die Abstimmungsübersicht sind als Rückkehrziel zulässig.