API-Design. Kai Spichale
Читать онлайн книгу.
müssen erweitert werden. Falls sich nun die Schnittstelle oder das bisherige Verhalten dieser Schnittstelle ändern würde, gäbe es Probleme bei der Integration in die Altsysteme. Deswegen muss bei jeder Änderung geprüft werden, ob diese negative Auswirkungen auf bestehende Benutzer hat und wie diese gegebenenfalls kommuniziert werden können. In Kapitel 7 werden wir uns anschauen, welche Änderungen kompatibel sind. Falls Änderungen nicht kompatibel sind, ist gegebenenfalls eine neue Version zu nutzen. Stabilität ist auch bei Einführung einer neuen Version wichtig, wenn Sie die Migration für existierende Clients möglichst einfach machen wollen.
2.2.9Einfach erweiterbar
Eine weitere Eigenschaft von APIs ist Änderbarkeit, ein zentrales Qualitätsmerkmal für Softwareprodukte. Man versteht darunter den erforderlichen Aufwand zur Durchführung vorgegebener Änderungen für Korrekturen, Verbesserungen oder Anpassungen an neue Anforderungen. Diese Eigenschaft ist kein Widerspruch zur zuvor genannten Stabilität, denn gemeint ist Folgendes:
Bei der Erweiterung einer API sollte der Änderungsaufwand für existierende Clients berücksichtigt werden. Im nächsten Abschnitt wird aus diesem Grund die Metrik Konnaszenz vorgestellt.
Im Idealfall ist die veränderte API kompatibel und der Clientcode muss überhaupt nicht angepasst werden.
Eine Java-API kann beispielsweise durch Vererbung erweitert werden:
API-Benutzer können durch Vererbung das Verhalten eines Frameworks anpassen oder ändern.
API-Entwickler können eine neue Subklasse hinzufügen, um auf kompatible Art und Weise neue Funktionen umzusetzen. Die neue Subklasse wird womöglich in einer Factory-Methode erzeugt, sodass API-Benutzer dies nicht bemerken.
Auch für Web-APIs ist Änderbarkeit ein wichtiges Qualitätsmerkmal. Flexible Datenformate wie XML und JSON können genutzt werden, um kompatible Erweiterungen umzusetzen.
2.3Konnaszenz
Für leicht änderbaren Code ist noch keine Zauberformel erfunden worden, aber mit Konnaszenz (engl. Connascence) steht ein gutes Modell zur Verfügung, mit dem wir zumindest über die Änderbarkeit von APIs sprechen können.
Was ist Konnaszenz?
Konnaszenz berücksichtigt verschiedene Typen von Kopplung sowie deren Häufigkeit und Lokalität für Aussagen über die Änderbarkeit von Code (The connascence.io website, 2018). Zwei Komponenten A und B gelten im Sinne von Konnaszenz als gekoppelt, falls eine Änderung an A eine Änderung an B erfordert, um die Korrektheit des Gesamtsystems zu gewährleisten. Eine starke Form von Konnaszenz zwischen A und B ist nur akzeptabel, wenn beide Komponenten eng beieinander liegen, weil sie zum Beispiel Teil derselben Codebasis sind. Umgekehrt ist eine starke Form von Konnaszenz zwischen Komponenten unterschiedlicher Systeme inakzeptabel. Es gilt: Je stärker die Konnaszenz zwischen A und B, desto schwieriger und aufwendiger sind deren Änderungen. Konnaszenz wird mit den Dimensionen Stärke, Häufigkeit und Lokalität beschrieben. Dies kann beim API-Design genutzt werden, um die Verbindung zwischen API und Client zu analysieren:
Stärke
Stärkere Formen von Konnaszenz sind schwerer zu finden oder zu ändern als leichtere Formen. Beispielsweise sind Namensänderungen leicht zu entdecken und durchzuführen. Im Vergleich dazu ist die Anpassung eines Algorithmus, der zwischen API und Client abgestimmt werden muss, schwierig.
Häufigkeit
Die Änderung einer API, die sehr viele Clients hat, ist höchstwahrscheinlich eine größere Herausforderung als die Änderung einer API mit wenigen Clients. Die Änderbarkeit von öffentlichen APIs mit vielen Clients ist daher stark eingeschränkt.
Lokalität
Je weiter API und Client entfernt sind, desto schwieriger sind Änderungen. Wenn API und Client zur selben Codebasis gehören, ist die Änderung vergleichsweise einfach. Änderungen innerhalb des Zuständigkeitsbereichs eines Entwicklungsteams sind ebenfalls akzeptabel. Aber Änderungen über Organisationsgrenzen hinweg sind deutlich komplexer, weil die Organisationen wahrscheinlich verschiedene Ziele verfolgen, unterschiedliche Releasezyklen haben und die Kommunikation insgesamt schwieriger oder aufwendiger ist als innerhalb eines Teams.
Statische Konnaszenz
Es gibt verschiedene Formen von Konnaszenz, die man in statisch und dynamisch einteilen kann. Statische Formen kann man durch Lesen des Codes finden und analysieren. Die folgende Liste ist nach aufsteigender Stärke sortiert:
Namenkonnaszenz
Die schwächste Form statischer Konnaszenz ist Namenskonnaszenz. In diesem Fall müssen sich mehrere Komponenten auf den Namen eines Elements einigen. Falls zum Beispiel ein Name im JSON-Payload einer API geändert wird, müssen auch die von diesem Format abhängigen Clients angepasst werden.
Typkonnaszenz
Mehrere Komponenten müssen sich auf den Typ eines Elements einigen. Die Änderung eines Integers im JSON-Format einer API in einen String ist eine inkompatible Änderung mit mittelschwacher Konnaszenz.
Bedeutungskonnaszenz
Mehrere Komponenten müssen sich auf die Bedeutung bestimmter Werte einigen. Wenn eine API in ein Feld preis statt des Nettopreises nun den Bruttopreis schreibt, müssen die Clients angepasst werden.
Positionskonnaszenz
Mehrere Komponenten müssen sich auf die Reihenfolge bestimmter Werte einigen. Die Reihenfolge von Parametern für einen API-Aufruf ist ein typisches Beispiel für Positionskonnaszenz.
Algorithmuskonnaszenz
Bei der stärksten Form statischer Konnaszenz müssen sich mehrere Komponenten auf einen bestimmten Algorithmus einigen. Verbindungen zwischen API und Clients dieser Stärke können nur mit großem Aufwand geändert werden, daher sollte man beim Entwurf einer API auf Algorithmuskonnaszenz achten und versuchen, diese zu minimieren. Denken Sie beispielsweise an IBANs, die einem bestimmten Format folgen. Der Algorithmus zur Validierung von IBANs wird von unzähligen Systemen genutzt. Eine Änderung dieses Algorithmus wäre äußerst schwierig.
Dynamische Konnaszenz
Wie bereits erwähnt wurde, gibt es neben den statischen auch dynamische Formen von Konnaszenz, die nachfolgend beschrieben werden:
Ausführungskonnaszenz
Die Methoden einer API können nur in spezieller Reihenfolge aufgerufen werden. Häufig gibt es einen offensichtlichen fachlich-logischen Grund, warum API-Methoden nicht in beliebiger Reihenfolge benutzt werden können. Nehmen wir zum Beispiel einen Webservice einer Shopping-Anwendung zum Verwalten von elektronischen Einkaufswagen. Man kann beispielsweise nicht mit einer Operation CartAdd einen Artikel in einen Einkaufskorb legen, wenn nicht zuvor mit einer Operation CartCreate ein entsprechendes Objekt (Einkaufskorb) mit dem Webservice erzeugt wurde.
Zeitliche Konnaszenz
Diese Form bezieht sich auf die zeitliche Koordinierung zwischen API und Client. Fachliche Transaktionen werden beispielsweise für