Breaking Change in /api/services

daniel-lerch

In einem der letzten Updates (welches kann ich leider nicht sagen) wurde in der REST API /api/services der Datentyp von data[i].groupIds stillschweigend von string auf number[] geändert. Die Open API Dokumentation zeigt noch den alten Datentyp.

Auch wenn der neue Datentyp deutlich mehr Sinn macht als eine mit Kommata getrennte Liste, ärgert es mich als Nutzer, dass solche Änderungen ohne Rücksicht auf Kompatibilität durchgeführt werden. Ich benutze nur einen Bruchteil der APIs von ChurchTools, aber das ist innerhalb von 13 Monaten jetzt schon der dritte Breaking Change.

Steht schon fest, ob diese Änderung so bleiben wird? Dann werde ich meinen Client entsprechend anpassen.

Und wäre es für die Zukunft eine Überlegung wert, einen automatisierten Test der API anhand der Open API Spezifikation in die CI Pipeline von ChurchTools einzubauen, damit solche Fehler in der Entwicklung früher auffallen? Ich weiß nicht, wie sinnvoll wir als Community dabei unterstützen könnten, aber falls es möglich ist, unterstütze ich gerne die Entwicklung eines solchen Tests.

davidschilling

@daniel-lerch Diese Änderung ist uns dann leider durchgerutscht. Wir geben uns große Mühe alle Änderungen möglichst Rückwärtskompatibel zu machen haben das in diesem Fall aber leider übersehen.

Ich kann dir jedenfalls Versichern, dass solche Änderungen nicht einfach ohne Rücksicht auf Kompatibilität gemacht haben.

Damit wir eine Möglichkeit haben in Zukunft auch Änderungen durchzuführen gibt es seit kurzem diese Seite https://churchtools.academy/de/help/system-einstellungen/api/0-deprecations/. Diese werden wir in Zukunft weiter pflegen.

Zusätzlich werden Mails versendet an den Nutzer von alten Apis oder Apis deren Parameter sich geändert haben.

Die Idee mit Tests dieser Art ist nicht schlecht. Ich schreib mir das mal auf. Allerdings ist das auch nicht einfach, weil nicht alle Breaking Changes ganz so einfach erkannt werden können.

Danke auf jedenfall fürs melden. Da das neue Schema besser ist als das alte und hier das Problem jetzt schon auftritt, würde ich dich bitten deinen Client anzupassen. Unsere Api-Doku hab ich für die nächste Version angepasst.

Wodurch ist der Fehler bei dir entstanden? Nutzt du das Feld der GruppenIds oder ist es einfach ein Typ Fehler? Bzw wie nutzt du die Ct Api?

daniel-lerch

@davidschilling Danke für die schnelle Antwort. Dann werde ich meinen Client anpassen.

Das Problem ist in meiner Anwendung Korga aufgetreten. Die ist in C# programmiert und deserialisiert die Antworten der API in Klassen. Wenn sich das Schema ändert, funktioniert das folglich nicht mehr. Aber auch in anderen Sprachen hätte es hier Probleme gegeben, schließlich braucht man andere Logik, um einen String an Kommata zu splitten und als Zahl zu parsen als über ein JSON Array zu iterieren.

Die Idee für einen automatisierten Test wäre, einen Schema Validator zu verwenden und mit der bestehenden Open API Spezifikation zu füttern. Dieser müsste dann auf einer Testinstanz mit Beispieldaten jeden Endpunkt einmal aufrufen und überprüfen, ob das Ergebnis mit dem Schema übereinstimmt. Ich habe noch keine Recherche unternommen, ob es ein solches Tool schon gibt, halte es aber für wahrscheinlich.

Mit nur einem Request pro Eintrag könnte es natürlich sein, dass man Pech hat und das entscheidende Feld für den Datensatz gerade null ist, aber es wäre zumindest schon mal ein Anfang.