API-Design. Kai Spichale

Чтение книги онлайн.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       Diese Form bezieht sich auf die zeitliche Koordinierung zwischen API und Client. Fachliche Transaktionen werden beispielsweise für den Check-out-Prozess der Shopping-Anwendung eingesetzt. Nach Ablauf einer Frist wird die Transaktion automatisch vom Webserver gelöscht, es sei denn, die Transaktion wird vorher vom Client erfolgreich beendet oder abgebrochen.

       Diese Form von Konnaszenz liegt vor, wenn sich mehrere Werte zusammen ändern müssen, wenn beispielsweise Client und Server sich auf bestimmte Zahlen einigen, um den Zustand von Bestellungen anzugeben. Eine Bestellung in Bearbeitung hat dann zum Beispiel den Wert 2 und eine abgeschlossene Bestellung den Wert 3.

       In diesem Fall müssen mehrere Komponenten dieselbe Entität referenzieren. Angenommen die zuvor erwähnte Shopping-Anwendung besteht aus mehreren getrennten Webservices für die Verwaltung der elektronischen Einkaufswagen, für den Check-out-Prozess und für die Artikelsuche. Identitätskonnaszenz liegt vor, wenn die Webservices für Check-out und Artikelsuche denselben Einkaufswagen referenzieren müssen.