RESTful API: Vorstellung

hbuerger

An verschiedenen Stellen im Forum wurde es schon erwähnt und endlich darf ich euch die neue REST API (Work in Progress) vorstellen. Im Folgenden möchte ich euch kurz die Hintergründe aufzeigen, den aktuellen Stand besprechen und die nächsten Schritte nennen.

Wo kommen wir her?

Es ist kein Geheimnis. ChurchTools ist fast 15 Jahre alt. In diesem Zeitraum ist die Codebase enorm gewachsen. Viele Features haben Einzug erhalten und es werden immer mehr. Wir haben fast 230.000 Zeilen Code! Das ist nicht wenig (kommt natürlich immer drauf an mit was man es vergleicht) und verlang viel Arbeit. Seit gut 2 Jahren setzten wir daher auf ein neues Framework und haben unsere Vorgehensweisen verbessert und angepasst. D.h. wir Überarbeiten Funktionen und machen sie zukunftssicherer. Dabei möchten wir unsere Systemarchitektur um neue Standards bereichern. Wir versprechen uns dadurch eine bessere Performance und Skalierbarkeit. Und ich muss sagen, die ersten Früchte sind davon schon zu sehen, wenn auch nicht auf dem ersten Blick.

Seit letztem Jahr arbeiten wir effektiv an einer App. Die kam ja im Dezember raus. Diese App ist es die maßgeblich diesen Prozess der Überarbeitung vorantreibt. Wir nutzen in der App ausschließlich die neue REST API. Aber woher kommt die denn? Genau hier liegt der Hase im Pfeffer. Wir programmieren die neue REST API, damit wir Features in der App abbilden können.

Diese neue API planen wir gründlich und dadurch dauert der Prozess gerade etwas länger, denn wir müssen jedes einzelne Feature noch mal anpacken und in einer zeitgemäßen Representation darstellen.

Das Ziel ist ganz klar, die alte API irgendwann komplett abzuschalten! Bis wir an diesen Punkt gelangt sind wird noch viel Wasser den Rhein hinunter fließen. Aber wir arbeiten daran!

Wo stehen wir gerade?

Die Frage die euch jetzt interessiert ist wohl: Wie nutzte ich die neue API?

Das ganze Vorgeplänkel musste sein, damit ihr versteht warum es scheinbar so schleppend vorran geht. Wir haben, wie man sich hoffentlich denken kann, noch nicht alles in der REST API drin. Aber einiges ist schon fertig und kann auch genutzt werden. Wir dokumentieren die neue API nach dem OpenAPI Standard (ja, endlich eine gescheite API Dokumentation). Ihr könnt euch die Doku jederzeit in eurer eigenen ChurchTools Installation angucken unter https://meine-gemeinde.church.tools/api (Statt meine-gemeinde einfach eure URL verwenden).

Diese Seite zeigt euch den aktuellen Stand der REST API für eure aktuelle CT Version an. Alles was ihr da seht könnt ihr mit dieser Installation nutzen. Wenn ihr ein Update macht werden die neuen Endpoints dort wieder gelistet. Zusätzlich könnt ihr jeden Endpoint sofort in der Doku ausprobieren.

VORSICHT: Jeder Request wird komplett auf der Installation ausgeführt und zwar mit genau den Rechten mit den ihr gerade eingeloggt seit. Seid ihr also als Super Admin eingeloggt dann seid vorsichtig, dass ihr nicht aus Versehen etwas löscht oder ändert!

Eure Hilfe: Wir möchten eine gute und vollständige Dokumentation haben. Solltet ihr also Unstimmigkeiten in der Dokumentation finden, wie z.B. daß anders Felder heißen als dokumentiert oder das etwas nicht klar gewesen ist, dann schreibt das gerne an den Support support@churchtools.de und wir werden das dann verbessern.

Die nächsten Schritte

Wir arbeiten aktuell in jedem Sprint weiter an der API. Manche Endpoints sind einfach und schnell implementiert, andere wiederum sind sehr komplex und benötigen viel viel Planung und Vorarbeit.

Da wir nach Bedarf arbeiten steht keine Roadmap fest in welcher Reihenfolge wir welche Features / Endpoints implementieren werden. Aber vielleicht so viel sei verraten: Schon bald möchten wir die Gruppen und Personen API fertig haben. Das sind zwei sehr schwierige Fälle, weil sehr viele Abhängigkeiten bestehen. Aber gleichzeitig sind es auch zwei Kernfunktionalitäten, die wir überall brauchen. Also wenn diese Endpoints fertig sind haben wir schonmal einen guten Ausgangspunkt.

Ich hoffe ihr freut euch auch über die neue API wie ich und bin auf euer Feedback gespannt.

aschild

Hallo,

das sind coole News, Danke

Aber...

wir machen selfhosting von CT und haben soeben auch auf die 3.43.1 aktualisiert.
Aber mit dem /api Aufruf erhalte ich nur ein

Page Not Found

The page you are looking for could not be found. Check the address bar to ensure your URL is spelled correctly. If all else fails, you can visit our home page at the link below.
Visit the Home Page

Braucht es da noch was in the .htaccess oder sonstwo damit es auch im selfhosting funktioniert?

MichaelG

@hbuerger sehr stark!

Ohne euch festnageln zu wollen: wann ist mit der Gruppen API zu Rechen... nächste Version, übernächste, ca 1 Monat, ca 3 Monate?

Wäre super hilfreich hier eine Einschätzung zu haben (wie gesagt, wenn es dann doch etwas länger wird, bin ich nicht böse, aber das würde bei einer Entscheidung helfen, die wir gerade treffen)

Gerne auch PN, falls du es nicht öffentlich sagen möchtest.

hbuerger

@aschild Mir ist beim Testen aufgefallen, dass der Link nur funktioniert wenn er nicht mit einem / (Slash) endet. Also /api ist ok aber /api/ nicht. Das werde ich noch beheben. War das zufällig auch bei dir so?

Die Seite sollte auf jeden Fall auch für Self-Hoster Kunden sichtbar sein. Falls das Problem noch weiter besteht würde ich dich gerne bitte dem Support zu schreiben (support@churchtools.de), dann können wir gerne noch mal genau auf deine Installation gucken.

hallo144

@aschild Also bei uns funktioniert es auch im Selbst-Hosting, scheint also kein generelles Problem zu sein.

hbuerger

@MichaelG Wir sind gerade an einem großen Thema dran, wofür wir allerdings "nur" die Gruppenteilnehmer benötigen. Die Endpoints um Gruppenteilnehmer für eine Gruppe zu bekommen, zu ändern, zu entfernen wird es bald geben (hoffentlich spätestens ab v3.45.x). Allerdings hier auch erstmal ohne Gruppenfelder. Das wird aber noch kommen.

Alle Gruppen zu sehen (GET) wird es schon mit der nächsten Version geben. Das Anlegen (POST), Ändern (PATCH) oder Löschen (DELETE) von Gruppen wird noch etwas dauern. Ein Zeitfenster kann ich dir leider nicht nennen. Aber ich persönlich würde mir wünschen, dass es bis zum Sommer drin wäre (da ich es private gut nutzen könnte ^^)

aschild

@hbuerger sagte in RESTful API: Vorstellung:

@aschild Mir ist beim Testen aufgefallen, dass der Link nur funktioniert wenn er nicht mit einem / (Slash) endet. Also /api ist ok aber /api/ nicht. Das werde ich noch beheben. War das zufällig auch bei dir so?

Die Seite sollte auf jeden Fall auch für Self-Hoster Kunden sichtbar sein. Falls das Problem noch weiter besteht würde ich dich gerne bitte dem Support zu schreiben (support@churchtools.de), dann können wir gerne noch mal genau auf deine Installation gucken.

Ja, genau das war es, ohne Abschliessenden / geht es und macht dann ein Redirect nach https://servername.domain.tld/api#/

Danke

artus70

Die App verwendet also bereits die API, und der aktuelle Stand der API ist unter /api dokumentiert? Wirklich beides?

Ich versuche nämlich gerade, mir anhand der Doku zusammenzureimen, was die App wohl macht, um mir meine Dienste anzuzeigen und mir dann auch die weiteren Beteiligten aufzulisten - und das gelingt mir nicht.

hbuerger

@artus70 Du bist sehr aufmerksam

Ja, die App verwendet die API und diese ist (noch nicht vollständig) dokumentiert. Gerade die Events und Dienste sind auch über die REST API abrufbar, aber haben wir noch nicht dokumentiert, weil wir hier noch mal genau drüber gucken wollen. Das werde ich aber schnellstmöglich nachholen

tomzi

For our church the https://xyz.church.tools/api does not work it only says 0_1554204083000_3cc56c50-123c-46fe-8454-6bc2d85f056b-image.png

why is that?

hallo144

@tomzi
The url only works if there is NO "/" (Slash) in the end

xyz.church.tools/api -> works
xyz.church.tools/api/ -> doesn't work

AGraf

Ich habe mir die RESTful API angeschaut und sie sieht sehr gut aus!
Vor allem die Doku mit Swagger ist genial.
Mir fiel auf, dass bei Gruppen /api/groups/{id} das Property "members" fehlt. In der Doku ist es vorhanden, bei meinen Antworten fehlt es. Die Properties "information", "settings", "followUp" sind da, nur "members" fehlt. Genau was ich brauche
Kann das Problem jemand nachvollziehen? CT-Version 3.45.0

hbuerger

@AGraf sagte in RESTful API: Vorstellung:

Mir fiel auf, dass bei Gruppen /api/groups/{id} das Property "members" fehlt.

Sehr gut aufgefallen. Das sollte nicht in der Doku sein. Wir haben uns erstmal dagegen entscheiden die Members in die Gruppen API reinzunehmen. Wir arbeiten an einem eigenen Members Endpoint, der ist aber noch nicht fertig. Ich behebe die Unstimmigkeiten in der Doku.

AGraf

Sehr gut! Habe auch erst mal nach /api/groups/{id}/members gesucht ....

philipptrenz

Hey, vielen Dank für das Bereitstellen der API.

Ich wurde von meiner Gemeinde angefragt, ob ich ein kleines Desktop-Tool schreiben kann, dass die Gottesdienstbesucher in ChurchTools einträgt ohne sich im Webportal einloggen zu müssen. Ist schon absehbar wann diese Funktionalität implementiert sein wird?

Vielen Dank!

hbuerger

@philipptrenz sagte in RESTful API: Vorstellung:

Hey, vielen Dank für das Bereitstellen der API.

Ich wurde von meiner Gemeinde angefragt, ob ich ein kleines Desktop-Tool schreiben kann, dass die Gottesdienstbesucher in ChurchTools einträgt ohne sich im Webportal einloggen zu müssen. Ist schon absehbar wann diese Funktionalität implementiert sein wird?

Vielen Dank!

Du meinst sicherlich die Fakten im Events Modul, oder? Nein darüber haben wir aktuell noch nicht gesprochen.

philipptrenz

@hbuerger Genau! Okay, aber ist der Events-Endpoint schon in Planung? Nachdem die Facts ja frei konfigurierbar sind würde ich für den Endpunkt einfach ein Array mit Key-Values zum Lesen und Setzen vorschlagen.

In etwa so

GET /events/{id}/facts

Returns: 
{
  "data": [
    {
      "key": "Besucherzahl",
      "value": 57
    },
    {
      "key": "Kollekte",
      "value": 0
    }
  ]
}

und

PUT /events/{id}/facts

Request body: 
{
  "data": [
    {
      "key": "Besucherzahl",
      "value": 57
    },
    {
      "key": "Kollekte",
      "value": 165
    }
  ]
}

Das sollte generisch genug sein, um auch spätere Erweiterungen an den Facts abbilden zu können.

Ich fände es klasse, wenn das Feature zeitnah Einzug erhält. Ich habe nämlich wenig Lust mich mit der alten API herumzuschlagen

Btw: Wird es eine veröffentlichte Swagger-Spezifikation für die API geben, um sich mit Swagger CodeGen den Client-Code generieren lassen zu können?

davidschilling

@philipptrenz sagte in RESTful API: Vorstellung:

Btw: Wird es eine veröffentlichte Swagger-Spezifikation für die API geben, um sich mit Swagger CodeGen den Client-Code generieren lassen zu können?

Diese Spezifikation gibt es schon. Eine Nutzung davon siehst du wenn du /api bei euch in der Installation aufrufst.
Die spezifikation findest du unter https://$DEINE_GEMEINDE.church.tools/system/runtime/swagger/openapi.json
$DEINE_GEMEInDE musst du natürlich austauschen.

philipptrenz

@davidschilling Perfekt, den Link zur JSON-Spezifikation hab ich gesucht. Danke dir!

MarkusFriesen

Hi @hbuerger. Vielen Dank für die API, bin gerade drauf gestoßen und finde sie super Hilfreicht!

Ich habe eine kurze frage zur Erweiterung. Ich habe es geschafft meine Gemeinde dazu zu überreden das wir unsere Lieder Datenbank in die Cloud zu ChurchTools ziehen.

Die Song api kann ja aber zur Zeit nur lesen. Habt ihr euch auch überlegt API's zum erstellen von Songs, und für das automatisierte hochlanden von z.b. songbeamer sng dateien zu ermöglichen?

Das wäre super Hilfreich.

Danke.