intuitives Feature ist die Möglichkeit, mehr als 60 Sekunden, mehr als 24 Stunden usw. bei der Erzeugung eines Date-Objektes anzugeben. Statt einer Fehlermeldung wird der Überhang korrekt berechnet. Durch eine Angabe von beispielsweise 25 Stunden wird der nächste Tag 1 Uhr ausgewählt. Dieses Verhalten ist nicht offensichtlich und könnte deswegen zu Fehlern führen.
2.2.7Minimal
Im Zweifel weglassen!
Eine API sollte prinzipiell so klein wie möglich sein, weil einmal hinzugefügte Elemente nachträglich nicht mehr entfernt werden können. Außerdem sind größere APIs auch komplexer. Dies hat Auswirkungen auf Verständlichkeit und Wartbarkeit der API. Ein ganz anderer Punkt ist der Implementierungsaufwand: Je größer die API, desto aufwendiger ihre Implementierung. Deswegen sollten beispielsweise zusätzliche Hilfsmethoden nur mit Bedacht hinzugefügt werden. Andererseits können Hilfsmethoden sehr nützlich sein. Überhaupt sollte ein Client nichts tun müssen, was eine API übernehmen kann.
Daher braucht man einen Kompromiss, wie ihn die Entwickler der Java-Collection-API gefunden haben: Mit den Methoden addAll und removeAll im Interface java.util.List können mit einem Aufruf mehrere Objekte zu einer Liste hinzugefügt bzw. entfernt werden. Diese Methoden sind optional, weil man Objekte auch einzeln mit add und remove hinzufügen bzw. entfernen kann. Trotzdem ist das Vorhandensein dieser Hilfsmethoden im Interface java.util.List nachvollziehbar und akzeptabel. Diese Hilfsmethoden werden sehr häufig verwendet und passen gut zum Rest des Interface. Andere Hilfsmethoden wie beispielsweise removeAllEven oder removeAllOdd, die alle Objekte mit gerader bzw. ungerader Positionsnummer aus einer Liste entfernen, wären für nur wenige spezielle Anwendungsfälle hilfreich und gehören deswegen nicht in die API.
Die Ruby-Standardbibliothek hat diverse Methoden mehrfach, weil man so im Clientcode besser ausdrücken kann, was man tut. Die Anzahl der Elemente eines Arrays kann z. B. mit length, count und size abgefragt werden. Das muss man nicht ermöglichen, aber es ist ein guter Stil, wenn man ihn konsistent anwendet.
Weniger ist manchmal mehr
Schweizer Messer sind bekannt für ihre zahlreichen Werkzeuge. Neben einer Klinge bieten sie z. B. eine Holzsäge, einen Korkenzieher, eine Schere, eine Metallfeile oder eine Pinzette. Manche dieser Werkzeuge werden kaum oder vielleicht nie benutzt. Ein gewöhnlicher Schraubenzieher mit einem vergleichsweise einfachen Design ist ebenfalls vielseitig einsetzbar: Man kann beispielsweise eine Farbdose mit ihm öffnen, falls der Deckel klemmt. Man kann mit ihm die Farbe umrühren, ein Loch in etwas machen, etwas hinter dem Schrank hervorholen, das man mit der Hand nicht erreichen kann, und man kann sogar Schrauben festdrehen.
Auch eine kleine einfache API kann vielseitig einsetzbar sein. Es muss nicht für jeden Sonderfall eine spezielle Funktion, die am Ende kaum jemand nutzen wird, eingebaut werden. Nichtsdestotrotz sind Schweizer Messer sehr nützlich.
2.2.8Stabil
Stabilität ist eine wichtige Eigenschaft von APIs. Angenommen Sie entwickeln einen Tarifrechner. Ihr Produkt wird ein großer Erfolg und soll in mehrere Kundensysteme integriert werden. Die Integrationen werden von unterschiedlichen Teams durchgeführt und sind relativ teuer, weil Altsysteme nur mit großem Aufwand angepasst werden können. Dann gibt es eine neue Anforderung aus der Fachabteilung und die komplexen Berechnungsregeln des Tarifrechners 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
