Breaking Change in /api/permissions/global
-
Als ich heute ein Programm weiterentwickeln wollte, mit dem ich vor ein paar Wochen angefangen hatte, staunte ich nicht schlecht. Die REST API
/api/permissions/globalwurde stillschweigend geändert.Das Attribut
data.churchdb.'view grouptype'existiert nicht mehr. Stattdessen gibt es jetzt ein Attributdata.churchdb.'view groups of grouptype'. Die OpenAPI Dokumentation unter/apizeigt noch den alten Namen an.Attribute an einer nicht experimentellen, öffentlichen API stillschweigend zu ändern, finde ich sehr problematisch. Wäre meine Anwendung bereits in Produktion, würde sie vom einen Tag auf den anderen nicht mehr funktionieren, sondern abstürzen.
Wenn ihr nicht mehrere Versionen der API pflegen wollt und kein Semantic Versioning für ganz ChurchTools verwenden wollt, kann ich das wegen des damit verbundenen Arbeitsaufwands verstehen.
Trotzdem würde ich mir wünschen, das solche Breaking Changes mindestens ein halbes Jahr in der OpenAPI Dokumentation deutlich sichtbar als Deprecated gekennzeichnet werden, bevor sie entfernt werden. Außerdem wäre es gut, wenn die Dokumentation entsprechend aktualisiert würde und Breaking Changes in den Release Notes erwähnt werden.
-
@daniel-lerch Hallo Daniel.
Das ist schlecht, dass das passiert ist. Normalerweise achten wir darauf.
Danke für den Hinweis.Was ist das für ein Programm in dem du die Berechtigungen nutzt?
-
@davidschilling Gut zu hören, dass ihr standardmäßig darauf achtet und dieser konkrete Fall ein unentdeckter Fehler ist und nicht als Refactoring so geplant war.
Ich möchte den Endpunkt in Korga einbauen, um Administratoren zu warnen, falls sie dem ChurchTools Konto für diese Anwendung zu wenige Rechte eingeräumt haben.
Viele Endpunkte der API geben - zu Recht - keinen 403 Forbidden zurück, sondern eine leere Liste. Stattet man jetzt den Nutzer von Korga mit zu wenigen Rechten aus, wundert man sich, wieso manche Funktionen nicht funktionieren. Damit Administratoren dann nicht lange nach dem Fehler suchen müssen, möchte ich eine Warnung anzeigen.
-
Heute ist mir aufgefallen, dass das Attribut
data.churchdb.'edit groups'nicht mehr existiert. Es gibt nur noch das Attributdata.churchdb.'edit group'. Ich brauche diese Attribute nicht, aber vor einiger Zeit gab es das noch und jetzt gibt es Fehler beim Mappen des JSON zu meiner Klasse.Wie beim letzten Mal taucht das Attribut außerdem weiterhin in der OpenAPI Dokumentation auf.
-
@davidschilling Die OpenAPI Dokumentation zu
/api/permissions/globalzeigt immer nochdata.churchdb.'edit groups': booleanan. Falls dieses Attribut nicht wieder hinzugefügt wird, was inhaltlich wahrscheinlich auch keinen Sinn ergäbe, wäre es super, wenn ihr die Dokumentation dahingehend aktualisieren könntet. -
@daniel-lerch Sprichst du nur den von Beispiel-Daten, die ergänzend angezeigt werden? Oder noch von etwas anderem?
-
@thommyb Ich meine die Beispiel-Daten. Das Schema war mir vorher noch gar nicht aufgefallen, aber im Schema sind für
/api/permissions/globalkaum Attribute definiert. Die meisten gibt es nur in den Beispiel-Daten. Verstehe ich die Dokumentation hier falsch und die Attribute sollen überhaupt keine sein, sondern eher eine Liste von Berechtigungen, wo jederzeit beliebige Berechtigungen entfernt und umbenannt werden können? -
@daniel-lerch die Beispiele können unter Umständen etwas outdated sein, relevant sind eigentlich die Attribute. Sind für die nächste Version für die GlobalPermissions nachgereicht
-
@jziegeler Ich habe jetzt die Liste von Attributen herangezogen und bin auf folgende Probleme gestoßen:
data.churchcore.'administer custom modules'unddata.churchcore.'use churchquery'werden als obligatorische Attribute aufgeführt, sind in der API Response aber nicht vorhandendata.churchcheckin,data.churchgroup,data.churchreportunddata.churchsyncwerden als obligatorische Attribute aufgeführt, sind in der API Response aber nicht vorhanden, falls die betreffenden Module deaktiviert sind.
-
@daniel-lerch danke für den Hinweis, habe ich für die nächste Version gefixt
