API & Deep-Linking: Feedback und Feature-Requests aus der Praxis (App-Integration)

[Tweiback]

Liebes ChurchTools-Team und liebe Community,

ich entwickle aktuell eine eigenständige Web-App für Chorleiter. Ein Feature dabei ist die Anbindung an ChurchTools: Wenn ein Chorleiter in der App einen Auftrittstermin öffnet, sucht die App über die API automatisch den passenden Gottesdienst und generiert einen Button, der den Nutzer mit einem Klick direkt zum entsprechenden Ablaufplan in ChurchTools führt.

Es ist wirklich klasse, dass das grds. schon mal mit der API funktioniert! Bei der praktischen Umsetzung und den Tests auf verschiedenen Endgeräten bin ich allerdings auf ein paar größere Probleme gestoßen, die den Workflow noch stark ausbremsen.
Daraus sind die folgenden vier Anmerkungen und Feature-Requests entstanden. Vielleicht habt ihr ja das ein oder andere davon ohnehin schon auf der Roadmap:

1. Fehlende CORS-Header an der REST-API
Wenn man eine eigenständige Web-App (Frontend-only) baut, verbieten moderne Browser direkte API-Abfragen an *.church.tools/api/..., da ChurchTools serverseitig keine CORS-Header (Access-Control-Allow-Origin) mitsendet. Um das zu umgehen, muss man als Drittentwickler zwingend einen eigenen Proxy-Server (z. B. via Cloudflare Workers) dazwischenschalten.
Mein Wunsch: Es wäre großartig, wenn man in den CT-Admin-Einstellungen für die API „Erlaubte Ursprünge“ (Allowed Origins/CORS) hinterlegen könnte. Alternativ könnten Lese-Zugriffe mit gültigem Login-Token prinzipiell von jedem Origin aus gestattet werden.

2. URL-Parameter wird durch Standort-Filter überschrieben (PC-Ansicht)
Ruft man am PC einen direkten Link zu einem Ablaufplan auf (z. B. /?q=churchservice&id=1234), ignoriert das ChurchTools-Frontend diese ID komplett, wenn der Nutzer in seiner letzten Sitzung einen anderen Standort (Campus) ausgewählt hatte. CT wendet stur den im LocalStorage gespeicherten Standort an und springt zum nächsten Gottesdienst dieses Standorts, anstatt das per ID angefragte Event zu öffnen.
Mein Wunsch: Ein expliziter URL-Parameter wie &id= sollte höchste Priorität haben und den lokal gespeicherten Standort-Filter automatisch anpassen.

3. Fehlendes Deep-Linking in die native App (Mobile-Ansicht)
Klickt man auf dem Smartphone auf einen Link zu einem Event oder Ablaufplan (egal ob /?q=churchservice&id=1234 oder /events/1234), wird dieser leider nicht von der ChurchTools-App abgefangen. Das Betriebssystem (iOS/Android) leitet den Nutzer stattdessen zwingend in den mobilen Webbrowser.
Mein Wunsch: Die Implementierung von umfassenden Universal Links/App Links. Geteilte Links zu Events und Ablaufplänen sollten zielsicher die native ChurchTools-App öffnen und direkt zur entsprechenden Ansicht springen.

4. Die Logik des to-Parameters bei /api/events
Fragt man die API nach Events für exakt einen Tag ab (z. B. ?from=2026-04-06&to=2026-04-06), liefert sie ein leeres Array zurück. Die API interpretiert das to-Datum strikt als 00:00:00 Uhr desselben Tages und schneidet somit den gesamten Tag ab. Man muss den to-Parameter künstlich auf den Folgetag setzen, um die Events des gesuchten Tages zu bekommen.
Mein Wunsch: Es wäre intuitiver (und Standard bei den meisten REST-APIs), wenn ein exaktes to-Datum „inclusive“ wäre (also bis 23:59:59 Uhr gilt) oder es alternativ einen einfachen Parameter ?date=YYYY-MM-DD gäbe.

Vielen Dank für eure tolle Arbeit an ChurchTools! Ich bin gespannt auf euer Feedback und ob sich einige dieser Punkte in Zukunft vielleicht umsetzen lassen.

[jziegeler]

@Tweiback 1. schau mal unter https://gemeinde.church.tools/settings/integrations/api/cors

[thommyb]

@Tweiback Ad 2. Warum holst du dir den Ablaufplan nicht per GET /events/<id>/agenda? Dann bekommst du zielsicher den richtigen.

Ad 4. Das exklusive to ist vielleicht zunächst unintuitiver, aber bei näherer Betrachtung dann doch nicht: Wenn man nämlich auch noch Tageszeiten angeben kann, dann ist 2026-03-26T12:00 als Ende natürlicherweise exklusiv, weil sich zwei Events, die jeweils um 12:00 enden bzw. beginnen, nicht überschneiden. Warum sollte das also bei Datümern (also Datum ohne Zeitangabe) anders sein oder sich gar unterschiedlich verhalten. (Disclaimer: Aktuell ist das bei ein oder zwei Endpunkten in CT noch so, aber davon wollen wir mittelfristig wegkommen).
Dass die meisten REST APIs das anders halten, möchte ich deshalb bezweifeln. Die Google KI spukt auf die Frage "API Ende inklusiv oder exklusiv - was ist besser?", die folgende Zusammenfassung aus:

Bei der API-Entwicklung (insbesondere bei Datumsspannen, Paginierung oder Indexbereichen) ist die Frage nach inklusiv (einschließlich) oder exklusiv (ausschließend) ein klassisches Designthema.
Die kurze Antwort: In der modernen REST-API-Entwicklung ist exklusiv (Endwert ausgeschlossen) im Allgemeinen besser und der Best-Practice-Ansatz.