Gelö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!

[sbellon]

@thommyb Cool, da ich selbst aus der Software Entwicklung komme (und wir Werkzeuge zur Qualitätssicherung für C/C++ verkaufen), ist das Loswerden von Altlasten und Herstellen von Konsistenz genau mein Ding.

Ich frage mich gerade, wie wir es aber hinbekommen können, so dass nicht eines Sonntags morgen, die Techniker bei uns am Rechner sitzen und unsere Anbindung crasht, weil unerwartete Daten zurückgegeben werden.

Letzte Woche ging das noch glimpflich aus, da ein Kollege das schon freitags ausprobiert und gemerkt hat, und ich noch samstags Zeit für die Anpassung hatte.

Ich werte sogar die @deprecated Felder im JSON aus, und gebe in der Entwicklungsversion entsprechende Rückmeldung, wenn der Code noch solche Felder verwendet.

Leider hilft das weder, wenn der String-Wert (!) sich von "normal" zu "text" ändert, noch wenn auf einmal im Schema zusätzlich null erlaubt ist.

Aber grundlegend: Verstehe ich dich richtig, dass an allen Stellen, an denen im Augenblick string zurück kommt, das Ziel ist, null anstelle eines Leerstrings zu liefern, so dass Anbindungen stets bei string auch mit null rechnen sollten?

Viele Grüße
Stefan

[thommyb]

@sbellon Ja, genau, zumindest für die optionalen strings (also meist Beschreibungen und ähnliches), die auch beim Anlegen nicht zwingend mitgegeben werden müssen. Felder, die erforderlich sind und auch meist eine Mindestlänge haben, können natürlich nicht null sein, auch zukünftig nicht.