Breaking Change in /api/permissions/global

daniel-lerch

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/global wurde stillschweigend geändert.

Das Attribut data.churchdb.'view grouptype' existiert nicht mehr. Stattdessen gibt es jetzt ein Attribut data.churchdb.'view groups of grouptype'. Die OpenAPI Dokumentation unter /api zeigt 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.

davidschilling

@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?

daniel-lerch

@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.

daniel-lerch

Heute ist mir aufgefallen, dass das Attribut data.churchdb.'edit groups' nicht mehr existiert. Es gibt nur noch das Attribut data.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.