Ungelöst Kürzliche undokumentierte REST-API Änderungen?

[sbellon]

Liebes ChurchTools-Team,

seit ein paar Tagen fällt uns auf, dass der REST-API Endpunkt /events/{eventId}/agenda sich an zwei kleinen Stellen verändert hat:

• bisher gab es die Typen "song", "header" und "normal", aber letzteres scheint jetzt zu "text" umbenannt worden zu sein, wobei sowohl die Dokumentation unter https://INSTANZ/api als auch https://INSTANZ/system/runtime/swagger/openapi.json noch "normal" liefert ... ist die Änderung beabsichtigt und dauerhaft oder ein Versehen?

• bisher gab es die Garantie, dass bei einem "song"-Element der "title" immer vom Typ string ist und "schlimmstenfalls" ein Leerstring, aber jetzt scheint es auch möglich, dass ein null zurückgeliefert wird ... auch hier wieder ohne Vermerk in der o.g. Dokumentation und daher mit der Frage: beabsichtigt und dauerhaft oder ein Versehen?

Vielen Dank für die Aufklärung diesbezüglich.

Viele Grüße
Stefan

[thommyb]

@sbellon Wir arbeiten gerade mit Hochdruck an den REST-APIs für den Ablaufplan (aus wahrscheinlich offensichtlichem Grund ).
In diesem Zug müssen wir leider auch die bereits bestehenden APIs nochmal anfassen, um alles unter einen Hut zu bekommen.

Wir optimieren auch die darunter liegenden Datenstrukturen für gute Performance auch bei komplexen Ablaufplänen (integriert, viele Dienste, viele Notizen). Das passt dann manchmal nicht mehr ganz zu den Strukturen, wie sie aktuell im API angeboten werden. Übergangsweise modellieren wir die nach, aber das soll natürlich nicht so bleiben, um wirklich mittelfristig alle Vorteile der neuen Strukturen zu nutzen.

Offenbar gab es da einige kleinere Dinge, die uns inmitten des großen Ganzen durchgerutscht sind. Wir wollen hier (wie schon an anderen Stellen) den Leerstring über kurz oder lang durch null ersetzen. Normalerweise machen wir das in zwei Schritten: erst den Typ erweitern und etwas später null statt '' zurückgeben, um euch etwas Zeit für die Anpassung zu geben. Das haben wir hier übersehen. Es wird noch eine .1 Version geben, wo wir Doku und diesen Zwischenschritt ergänzen.

Bei den Typen ist text tatsächlich das neue normal. Der Typ normal ist in diesem Zusammenhang recht nichtssagend, auch im Blick auf potenziell weitere Typen. Im noch unsichtbaren Teil der REST-APIs ist das bereits dokumentiert, aber hier haben wir eine Stelle vergessen. Das wird ebenfalls umgehend ergänzt.

Wie gesagt: Rund um den Ablaufplan ist gerade eine Menge Bewegung. Wir hoffen, den vollständigen Satz an APIs in einer der nächsten Versionen veröffentlichen zu können. Stay tuned!