Beherrschung der API-Architektur

Einführung

In dieser Einführung lernst du die Grundlagen von APIs und ihr Potenzial als Teil der Architektur kennen. Wir stellen eine leichtgewichtige Definition für APIs und ihre Verwendung innerhalb und außerhalb des Prozesses vor. Um die Bedeutung von APIs zu verdeutlichen, stellen wir die Fallstudie des Konferenzsystems vor, ein laufendes Beispiel, das sich im Laufe des Buches weiterentwickeln wird. Außerprozessuale APIs ermöglichen es dir, über eine einfache dreistufige Architektur hinaus zu denken; wir werden Verkehrsmuster und ihre Bedeutung vorstellen, um dies zu demonstrieren. Wir werden die Schritte der Fallstudie zusammenfassen, so dass du überspringen kannst, wenn ein Bereich für dich gerade interessant ist.

Um APIs und das damit verbundene Ökosystem vorzustellen, werden wir eine Reihe wichtiger Artefakte verwenden. Wir werden die Fallstudie mit C4-Modelldiagrammen einführen und die Besonderheiten und die Logik hinter dem Ansatz wiederholen. Du wirst auch etwas über die Verwendung von Architektur-Entscheidungsprotokollen (Architecture Decision Records, ADRs) und den Wert einer klaren Definition von Entscheidungen über den gesamten Software-Lebenszyklus hinweg erfahren. Zum Abschluss der Einführung werden wir die ADR-Richtlinien erläutern - unseren Ansatz, der dir hilft, Entscheidungen zu treffen, wenn die Antwort "es kommt darauf an" lautet.

Die Architektur-Reise

Jeder, der schon einmal eine lange Reise unternommen hat, wird zweifelsohne der Frage begegnet sein : "Sind wir schon da?"Bei den ersten Anfragen schaust du auf das GPS oder einen Routenplaner und gibst eine Schätzung ab - in der Hoffnung, dass du unterwegs auf keine Verzögerungen stößt. In ähnlicher Weise kann die Reise zum Aufbau API-basierter Architekturen für Entwickler und Architekten komplex sein; selbst wenn es ein Architektur-GPS gäbe, was wäre dein Ziel?

Architektur ist eine Reise ohne Ziel, und du kannst nicht vorhersagen, wie sich Technologien und architektonische Ansätze verändern werden. Du hättest zum Beispiel nicht vorhersagen können, dass die Service Mesh-Technologie so weit verbreitet sein würde, aber wenn du erst einmal von ihren Möglichkeiten erfährst, kann das dazu führen, dass du über die Weiterentwicklung deiner bestehenden Architektur nachdenkst. Nicht nur Technologien beeinflussen den Wandel in der Architektur, sondern auch neue geschäftliche Anforderungen und Zwänge treiben den Wandel in der Architektur voran.

Der kulminierende Effekt der inkrementellen Wertschöpfung in Kombination mit neuen, aufstrebenden Technologien führt zum Konzept der evolutionären Architektur. Die evolutionäre Architektur ist ein Ansatz zur inkrementellen Veränderung einer Architektur, der sich auf die Fähigkeit konzentriert, sich schnell zu verändern und das Risiko negativer Auswirkungen zu verringern. Auf dem Weg dahin bitten wir dich, die folgenden Ratschläge für die Herangehensweise an die API-Architektur zu beachten:

Obwohl Architekten gerne strategisch für die Zukunft planen, macht das sich ständig verändernde Ökosystem der Softwareentwicklung dies schwierig. Da wir den Wandel nicht vermeiden können, müssen wir ihn nutzen.

Building Evolutionary Architectures von Neal Ford, Rebecca Parsons und Patrick Kua (O'Reilly)

In vielen Projekten sind APIs selbst evolutionär und müssen geändert werden, wenn mehr Systeme und Dienste integriert werden. Die meisten Entwickler haben Dienste entwickelt, die sich auf eine einzelne Funktion konzentrieren, ohne die breitere API-Wiederverwendung aus der Perspektive der Verbraucher zu berücksichtigen.

API-First-Design ist ein Ansatz, bei dem Entwickler und Architekten die Funktionalität ihres Dienstes berücksichtigen und eine API verbraucherorientiert entwerfen. Der API-Verbraucher kann eine mobile Anwendung, ein anderer Dienst oder sogar ein externer Kunde sein. In Kapitel 1 werden wir Entwurfstechniken zur Unterstützung eines API-First-Ansatzes besprechen und herausfinden, wie wir APIs erstellen, die sich dauerhaft ändern und einer breiten Verbraucherbasis einen Mehrwert bieten.

Die gute Nachricht ist, dass du die Reise zu einer API-gesteuerten Architektur jederzeit beginnen kannst. Wenn du für ein bereits bestehendes technisches Inventar verantwortlich bist, zeigen wir dir Techniken, wie du deine Architektur weiterentwickeln kannst, um die Nutzung von APIs in deiner Plattform zu fördern. Wenn du hingegen Glück hast und mit einer leeren Leinwand arbeiten kannst, teilen wir mit dir die Vorteile der Einführung von API-Architekturen, die auf unserer langjährigen Erfahrung basieren, und heben gleichzeitig die Schlüsselfaktoren für die Entscheidungsfindung hervor.

Eine kurze Einführung in APIs

Im Bereich der Softwarearchitektur gibt es eine Handvoll Begriffe, die unglaublich schwer zu definieren sind. Der Begriff API, der für Application Programming Interface (Anwendungsprogrammierschnittstelle) steht, fällt in diese Kategorie, da das Konzept bereits vor 80 Jahren zum ersten Mal auftauchte. Begriffe, die schon sehr lange existieren, werden überstrapaziert und haben in verschiedenen Problembereichen mehrere Bedeutungen. Wir verstehen unter einer API Folgendes:

• Eine API stellt eine Abstraktion der zugrunde liegenden Implementierung dar.

• Eine API wird durch eine Spezifikation dargestellt, die Typen einführt. Entwickler können die Spezifikationen verstehen und mit Hilfe von Tools Code in mehreren Sprachen erzeugen, um einen API-Consumer (Software, die eine API nutzt) zu implementieren.

• Eine API hat eine definierte Semantik oder ein Verhalten, um den Austausch von Informationen effektiv zu modellieren.

• Ein effektives API-Design ermöglicht die Erweiterung auf Kunden oder Dritte für eine Geschäftsintegration.

Im Großen und Ganzen lassen sich APIs in zwei allgemeine Kategorien einteilen, je nachdem, ob der API-Aufruf prozessintern oder prozessextern erfolgt. Der Prozess, auf den hier Bezug genommen wird, ist ein Prozess des Betriebssystems (OS). Ein Java-Methodenaufruf von einer Klasse zu einer anderen ist beispielsweise ein prozessinterner API-Aufruf, da der Aufruf von demselben Prozess bearbeitet wird, von dem aus der Aufruf erfolgt ist. Eine .NET-Anwendung, die eine externe REST-ähnliche API über eine HTTP-Bibliothek aufruft, ist ein prozessfremder API-Aufruf, da der Aufruf von einem zusätzlichen externen Prozess bearbeitet wird, der nicht der Prozess ist, von dem aus der Aufruf erfolgt. Typischerweise werden bei einem prozessfremden API-Aufruf Daten über ein Netzwerk übertragen, z. B. über ein lokales Netzwerk, eine virtuelle private Cloud (VPC) oder das Internet. Wir werden uns auf die letztgenannte Art von APIs konzentrieren; Architekten werden jedoch häufig mit der Anforderung konfrontiert, eine prozessinterne API in eine prozessfremde API umzuwandeln. Um dieses Konzept (und andere) zu veranschaulichen, werden wir eine laufende Fallstudie erstellen, die sich im Laufe des Buches weiterentwickeln wird.

Laufendes Beispiel: Fallstudie Konferenzsystem

Wir haben uns für unsere Fallstudie für die Modellierung eines Konferenzsystems entschieden, weil die Domäne leicht erkennbar ist, aber auch genug Komplexität bietet, um eine evolutionäre Architektur zu modellieren.Abbildung I-1 visualisiert das Konferenzsystem auf oberster Ebene, um den Kontext der diskutierten Architektur zu verdeutlichen. Das System wird von einem externen Kunden genutzt, um sein Teilnehmerkonto zu erstellen, die verfügbaren Konferenzsitzungen zu überprüfen und seine Teilnahme zu buchen.

Abbildung I-1. Kontextdiagramm des C4-Konferenzsystems

Vergrößern wir den Kasten des Konferenzsystems in Abbildung I-2. Wenn wir das Konferenzsystem erweitern, erhalten wir mehr Details über seine wichtigsten technischen Bausteine. Der Kunde interagiert mit der Webanwendung, die APIs auf der Konferenzanwendung aufruft. Die Konferenzanwendung verwendet SQL, um den Backing-Datenspeicher abzufragen.

Abbildung I-2. Containerdiagramm des C4-Konferenzsystems

Abbildung I-2 zeigt, dass sich die interessantesten Funktionen aus API-Sicht im Container der Konferenzanwendung befinden.Abbildung I-3 zoomt auf diesen speziellen Container und ermöglicht es dir, die Struktur und die Interaktionen zu untersuchen.

Am aktuellen System sind vier Hauptkomponenten und die Datenbank beteiligt. Der API-Controller ist für den gesamten eingehenden Datenverkehr von der Benutzeroberfläche zuständig und trifft die Entscheidung, wohin die Anfrage im System geleitet werden soll. Diese Komponente ist auch für das Marshalling von der Darstellung auf Netzwerkebene zu einem Objekt oder einer Darstellung im Code verantwortlich. Die API-Controller-Komponente ist aus der Perspektive des prozessinternen Routings faszinierend und fungiert als Knotenpunkt oder Front-Controller-Muster. Für API-Anfragen und deren Verarbeitung ist dies ein wichtiges Muster; alle Anfragen durchlaufen den Controller, der die Entscheidung trifft, wohin die Anfrage geleitet wird. In Kapitel 3 werden wir uns mit der Möglichkeit befassen, den Controller aus dem Prozess herauszunehmen.

Die Komponenten "Teilnehmer", " Buchung" und " Sitzung" sind daran beteiligt, die Anfragen in Abfragen umzuwandeln und SQL außerhalb des Prozesses gegen die Datenbank auszuführen. In der bestehenden Architektur ist die Datenbank eine wichtige Komponente, die Beziehungen erzwingen kann, z. B. Beschränkungen zwischen Buchungen und Sitzungen.

Abbildung I-3. Diagramm der Komponenten des C4-Konferenzsystems

Jetzt, wo wir bis zur richtigen Detailebene vorgedrungen sind, wollen wir uns die Arten von API-Interaktionen in der Fallstudie unter noch einmal ansehen.

Arten von APIs in der Fallstudie der Konferenz

In Abbildung I-3 ist der Pfeil von der Webanwendung zum API-Controller ein Out-of-Process-Aufruf, während der Pfeil vom API-Controller zur Teilnehmerkomponente ein Beispiel für einen In-Process-Aufruf ist. Alle Interaktionen innerhalb der Grenzen der Konferenzanwendung sind Beispiele für In-Process-Aufrufe. Der In-Process-Aufruf ist genau definiert und wird durch die Programmiersprache eingeschränkt, die für die Implementierung der Konferenzanwendung verwendet wird. Der Aufruf ist kompiliersicher (die Bedingungen, unter denen der Austauschmechanismus beim Schreiben des Codes erzwungen wird).

Gründe für die Änderung des Konferenzsystems

Der derzeitige architektonische Ansatz von hat für das Konferenzsystem viele Jahre lang funktioniert, aber der Eigentümer der Konferenz hat drei Verbesserungen gefordert, die eine Änderung der Architektur erforderlich machen:

• Die Organisatoren der Konferenz würden gerne eine mobile Anwendung erstellen.

• Die Konferenzorganisatoren planen, ihr System zu globalisieren und statt einer Konferenz pro Jahr mehrere zu veranstalten. Um diese Expansion zu erleichtern, möchten sie ein externes Call for Papers (CFP) System integrieren, um Redner/innen und ihre Bewerbungen für Vorträge auf der Konferenz zu verwalten.

• Die Organisatoren der Konferenz möchten ihr privates Rechenzentrum stilllegen und stattdessen das Konferenzsystem auf einer Cloud-Plattform mit globaler Reichweite betreiben.

Unser Ziel ist es, das Konferenzsystem so zu migrieren, dass es die neuen Anforderungen unterstützen kann, ohne das bestehende Produktionssystem zu beeinträchtigen oder alles auf einmal neu zu schreiben.

Von der Tiered Architecture zur Modellierung von APIs

Ausgangspunkt der Fallstudie ist eine typische dreistufige Architektur, die aus einer Benutzeroberfläche, einer serverseitigen Verarbeitungsebene und einem Datenspeicher besteht. Um eine evolutionäre Architektur zu erörtern, brauchen wir ein Modell für die Art und Weise, wie API-Anfragen von den Komponenten verarbeitet werden. Wir brauchen ein Modell/eine Abstraktion, die sowohl für die öffentliche Cloud als auch für virtuelle Maschinen in einem Rechenzentrum und einen hybriden Ansatz funktioniert.

Die Abstraktion des Datenverkehrs ermöglicht es uns, die prozessfremden Interaktionen zwischen einem API-Konsumenten und einem API-Dienst, der manchmal auch als API-Produzent bezeichnet wird, zu berücksichtigen. Bei Architekturansätzen wie der serviceorientierten Architektur (SOA) und der auf Microservices basierenden Architektur ist die Modellierung von API-Interaktionen von entscheidender Bedeutung. Das Wissen über den API-Datenverkehr und die Art der Kommunikation zwischen den Komponenten wird den Unterschied ausmachen, ob die Vorteile einer stärkeren Entkopplung genutzt werden oder ob ein Wartungsalptraum entsteht.

Warnung

Verkehrsmuster werden von Rechenzentrumsingenieuren verwendet, um den Netzwerkaustausch innerhalb von Rechenzentren und zwischen Low-Level-Anwendungen zu beschreiben. Auf der API-Ebene verwenden wir Verkehrsmuster, um die Ströme zwischen Gruppen von Anwendungen zu beschreiben. Für die Zwecke dieses Buches beziehen wir uns auf Verkehrsmuster auf Anwendungs- und API-Ebene.

Fallstudie: Ein evolutionärer Schritt

Um zu beginnen, die Arten von Verkehrsmustern zu berücksichtigen, ist es sinnvoll, einen kleinen Evolutionsschritt in unserer Fallstudienarchitektur zu machen. In Abbildung I-4 wurde ein Schritt unternommen, um die Teilnehmerkomponente in einen eigenständigen Dienst umzuwandeln, im Gegensatz zu einem Paket oder Modul innerhalb des Legacy-Konferenzsystems. Das Konferenzsystem hat jetzt zwei Verkehrsflüsse: die Interaktion zwischen dem Kunden und dem Legacy-Konferenzsystem und die Interaktion zwischen dem Legacy-System und dem Teilnehmersystem.

Abbildung I-4. C4-Konferenzsystem Kontext-Evolutionsschritt

Nord-Süd-Verkehr

In Abbildung I-4 wird die Interaktion zwischen dem Kunden und dem alten Konferenzsystem als Nord-Süd-Verkehr bezeichnet und stellt einen Ingress-Fluss dar. Der Kunde nutzt die Benutzeroberfläche, die über das Internet Anfragen an das alte Konferenzsystem sendet. Dies ist ein Punkt in unserem Netzwerk, der öffentlich zugänglich ist und auf den die Benutzeroberfläche zugreifen kann.¹ Das bedeutet, dass jede Komponente, die den Nord-Süd-Verkehr verarbeitet, die Identität des Kunden konkret überprüfen und geeignete Herausforderungen einbauen muss, bevor sie den Verkehr durch das System passieren lässt.In Kapitel 7 wird die Absicherung des Nord-Süd-API-Verkehrs näher erläutert.

Ost-West-Verkehr

Die neue Interaktion zwischen dem alten Konferenzsystem und dem Teilnehmerdienst führt einen Ost-West-Verkehrsfluss in unser System ein. Der Ost-West-Verkehr kann als eine Art Kommunikation von Dienst zu Dienst innerhalb einer Gruppe von Anwendungen betrachtet werden. Der meiste Ost-West-Verkehr kann bis zu einem gewissen Grad als vertrauenswürdig eingestuft werden, vor allem, wenn der Ursprung innerhalb der breiteren Infrastruktur liegt. Obwohl wir der Quelle des Verkehrs vertrauen können, ist es dennoch notwendig, den Ost-West-Verkehr zu sichern .

API-Infrastruktur und Verkehrsmuster

gibt es zwei wichtige Infrastrukturkomponenten in API-basierten Architekturen, die für die Steuerung des Verkehrs von zentraler Bedeutung sind. Die Steuerung und Koordinierung des Verkehrs wird oft als Verkehrsmanagement bezeichnet. Im Allgemeinen wird der Nord-Süd-Verkehr von API-Gateways gesteuert, die in Kapitel 3 behandelt werden.

Der Ost-West-Verkehr wird oft von Infrastrukturkomponenten wie Kubernetes oder Service Mesh abgewickelt, dem Hauptthema von Kapitel 4. Infrastrukturkomponenten wie Kubernetes und Service Mesh nutzen Netzwerkabstraktionen, um zu den Diensten zu routen, was voraussetzt, dass die Dienste innerhalb einer verwalteten Umgebung laufen. In einigen Systemen wird der Ost-West-Verkehr von der Anwendung selbst verwaltet und es werden Techniken zur Erkennung von Diensten implementiert, um andere Systeme zu finden.

Fahrplan für die Konferenz Fallstudie

Im Laufe des Buches wirst du die folgenden Veränderungen oder Anwendungen von Technologie in der Fallstudie beobachten:

• In Kapitel 1 lernst du das Design und die Spezifikation der Attendee API kennen und erfährst, wie wichtig die Versionierung und die Modellierung des Austauschs für die Leistung der Attendee API sind.

• In Kapitel 2 wirst du dich mit Vertrags- und Komponententests beschäftigen, um das Verhalten des Attendee-Dienstes zu überprüfen. Du wirst auch sehen, wie Testcontainer bei Integrationstests helfen können.

• In Kapitel 3 wirst du dir ansehen, wie du den Attendee-Dienst mithilfe eines API-Gateways für Verbraucher zugänglich machst. Außerdem zeigen wir dir, wie du das Konferenzsystem mithilfe eines API-Gateways auf Kubernetes weiterentwickeln kannst.

• In Kapitel 4 werden wir die Sitzungsfunktionalität aus dem alten Konferenzsystem mit Hilfe eines Service Mesh umstrukturieren. Du wirst auch erfahren, wie das Service Mesh beim Routing, der Beobachtbarkeit und der Sicherheit hilft.

• In Kapitel 5 besprechen wir das Feature-Flagging und wie es dabei helfen kann, das Konferenzsystem weiterzuentwickeln und ein gekoppeltes Deployment und Release zu vermeiden. Du wirst auch Ansätze für die Modellierung von Releases im Konferenzsystem kennenlernen und wir werden die Verwendung von Argo Rollouts für den Attendee Service demonstrieren.

• In Kapitel 6 erfährst du, wie du die Bedrohungsmodellierung anwendest und die OWASP-Bedenken im Attendee-Dienst entschärfen kannst.

• In Kapitel 7 wirst du dich mit der Authentifizierung und Autorisierung befassen und wie diese für den Teilnehmerdienst implementiert wird.

• In Kapitel 8 beschäftigst du dich mit der Festlegung der Grenzen des Teilnehmerdienstes und damit, wie verschiedene Dienstmuster helfen können.

• In Kapitel 9 beschäftigst du dich mit der Cloud-Einführung und damit, wie du den Attendee-Dienst in die Cloud verlagern und eine Replattformierung in Betracht ziehen kannst.

Die Fallstudie und die geplante Roadmap erfordern die Visualisierung von Architekturänderungen und die Aufzeichnung von Entscheidungen. Dies sind wichtige Artefakte, die dabei helfen, Änderungen in Softwareprojekten zu erklären und zu planen. Wir glauben, dass C4-Diagramme und Architekturentscheidungsprotokolle (ADRs) eine klare Möglichkeit darstellen, Änderungen aufzuzeichnen.

C4-Diagramme verwenden

Als Teil der Einführung in die Fallstudie haben wir drei Arten von C4-Diagrammen aus dem C4-Modell vorgestellt. Wir sind der Meinung, dass C4 der beste Dokumentationsstandard ist, um Architektur, Kontext und Interaktionen an eine Vielzahl von Stakeholdern zu kommunizieren. Du fragst dich vielleicht, was mit UML ist? Die Unified Modeling Language (UML) bietet einen umfangreichen Dialekt für die Kommunikation von Software-Architekturen. Eine große Herausforderung ist, dass der Großteil dessen, was UML bietet, von Architekten und Entwicklern nicht im Gedächtnis behalten wird und die Leute schnell auf Kästchen/Kreise/Diamanten zurückgreifen. Es wird zu einer echten Herausforderung, die Struktur der Diagramme zu verstehen, bevor man sich mit dem technischen Inhalt der Diskussion befasst. Viele Diagramme werden nur dann in die Projektgeschichte aufgenommen, wenn jemand versehentlich einen Permanentmarker statt eines trocken abwischbaren Markers benutzt. Das C4-Modell bietet eine vereinfachte Reihe von Diagrammen, die als Leitfaden für deine Projektarchitektur auf verschiedenen Detailebenen dienen.

C4-Kontextdiagramm

Abbildung I-1 wird unter mit Hilfe eines C4-Kontextdiagramms aus dem C4-Modell dargestellt. Dieses Diagramm soll sowohl einem technischen als auch einem nicht-technischen Publikum den Kontext verdeutlichen. Viele Architekturgespräche tauchen direkt in die Low-Level-Details ein und verpassen es, den Kontext der High-Level-Interaktionen darzustellen. Bedenke, welche Folgen es hat, wenn ein Systemkontextdiagramm falsch verstanden wird - der Vorteil einer Zusammenfassung des Ansatzes kann Monate an Arbeit sparen, um ein Missverständnis zu korrigieren.

C4 Container Diagramm

Während Abbildung I-1 unter das Gesamtbild des Konferenzsystems darstellt, hilft ein Containerdiagramm dabei, die technische Aufteilung der Hauptakteure in der Architektur zu beschreiben. Ein Container ist in C4 definiert als "etwas, das laufen muss, damit das Gesamtsystem funktioniert" (z.B. die Konferenzdatenbank). Containerdiagramme sind technischer Natur und bauen auf dem übergeordneten Systemkontextdiagramm auf.Abbildung I-2, ein Containerdiagramm, dokumentiert die Details der Interaktion eines Kunden mit dem Konferenzsystem.

Hinweis

Der Konferenzanwendungscontainer in Abbildung I-2 ist als einfache Software dokumentiert. Normalerweise würde ein C4-Container mehr Details über die Art des Containers liefern (z. B. Java Spring Application). In diesem Buch werden wir jedoch Technologiespezifika vermeiden, es sei denn, es hilft, eine bestimmte Lösung zu demonstrieren. Der Vorteil von APIs und modernen Anwendungen ist, dass es eine große Flexibilität im Lösungsraum gibt.

C4-Komponenten-Diagramm

Das C4-Komponentendiagramm in Abbildung I-3 hilft dabei, die Rollen und Verantwortlichkeiten innerhalb jedes Containers sowie die internen Interaktionen zu definieren. Dieses Diagramm ist nützlich, wenn die Details eines Containers abgefragt werden, und es bietet auch eine sehr nützliche Karte der Codebasis. Wenn du zum ersten Mal an einem neuen Projekt arbeitest, ist es schwierig, sich in einer selbstdokumentierten Codebasis zurechtzufinden. Ein Komponentendiagramm zeigt dir die Details der Sprache/des Stacks, mit der/dem du deine Software erstellst. Um technologieunabhängig zu bleiben, haben wir den Begriff Paket/Modul verwendet.

Architektur-Entscheidungssätze verwenden

Als Entwickler, Architekten und auch als Menschen sind wir alle schon einmal in der Situation gewesen, in der wir uns die Frage gestellt haben : "Was haben die sich dabei gedacht?"Wenn du jemals auf der M62 zwischen Leeds und Manchester in Großbritannien gefahren bist, hat dich der Bau der Autobahn vielleicht verblüfft. Wenn du auf der dreispurigen Autobahn den Hügel hinauffährst, weicht sie von der Gegenfahrbahn ab, bis schließlich die Scott Hall Farm auftaucht, umgeben von etwa 15 Hektar Ackerland, das zwischen den Wagen liegt. Die örtliche Legende beschreibt den Besitzer des Landes als stur und weigerte sich, sein Land zu räumen oder zu übergeben, also bauten die Ingenieure einfach um ihn herum.² Fünfzig Jahre später tauchte ein Dokumentarfilm auf, der enthüllte, dass der wahre Grund dafür eine geologische Verwerfung unter dem Land war, weshalb die Autobahn auf diese Weise gebaut werden musste. Wenn Menschen raten, warum etwas auf eine bestimmte Art und Weise gemacht wurde, erwarten sie, dass Gerüchte, Humor und Kritik aufkommen.

In der Softwarearchitektur gibt es viele Einschränkungen, um die herum wir bauen müssen. Deshalb ist es wichtig, dass unsere Entscheidungen aufgezeichnet und transparent sind. ADRs helfen dabei, Entscheidungen in der Softwarearchitektur klar zu machen.

Eines der schwierigsten Dinge, die man im Laufe eines Projekts nachvollziehen kann, ist die Motivation hinter bestimmten Entscheidungen. Eine neue Person, die zu einem Projekt stößt, ist vielleicht verwirrt, verblüfft, erfreut oder wütend über eine frühere Entscheidung.

Michael Nygard, Erfinder des ADR-Konzepts

Es gibt vier wichtige Abschnitte in einem ADR: Status, Kontext, Entscheidung und Konsequenzen. Ein ADR wird in einem vorgeschlagenen Status erstellt und nach der Diskussion in der Regel entweder angenommen oder abgelehnt. Es ist auch möglich, dass die Entscheidung zu einem späteren Zeitpunkt durch eine neue ADR ersetzt wird. Der Kontext hilft dabei, den Rahmen abzustecken und das Problem oder den Rahmen, in dem die Entscheidung getroffen wird, zu beschreiben. Obwohl es der Gemeinschaft hilft, deine Arbeit zu verfolgen, wenn du vor der ADR einen Blogbeitrag erstellst und diesen dann verlinkst, ist der Kontext nicht als Blogbeitrag oder detaillierte Beschreibung gedacht. In der Entscheidung wird klar dargelegt, was du zu tun gedenkst und wie du es zu tun gedenkst. Alle Entscheidungen haben Konsequenzen oder Kompromisse in der Architektur, und diese können manchmal unglaublich kostspielig sein, wenn sie falsch getroffen werden.

Bei der Überprüfung eines ADR ist es wichtig zu sehen, ob du mit der Entscheidung im ADR übereinstimmst oder ob es einen alternativen Ansatz gibt. Ein alternativer Ansatz, der nicht in Betracht gezogen wurde, kann dazu führen, dass das ADR abgelehnt wird. Ein abgelehntes ADR ist sehr wertvoll und die meisten Teams entscheiden sich dafür, ADRs unveränderbar zu halten, um den Perspektivenwechsel festzuhalten. ADRs funktionieren am besten, wenn sie an einem Ort präsentiert werden, an dem die wichtigsten Teilnehmer sie sehen, kommentieren und dazu beitragen können, dass das ADR angenommen wird.

Tipp

Eine Frage, die uns oft gestellt wird, ist, zu welchem Zeitpunkt das Team ein ADR erstellen sollte. Es ist sinnvoll, sicherzustellen, dass im Vorfeld des ADR eine Diskussion stattgefunden hat und die Aufzeichnung das Ergebnis des kollektiven Denkens im Team ist. Die Veröffentlichung eines ADR in der breiteren Gemeinschaft bietet die Möglichkeit, über das unmittelbare Team hinaus Feedback zu erhalten.

Teilnehmer Entwicklung ADR

In Abbildung I-4 haben wir die Entscheidung getroffen, einen evolutionären Schritt in der Architektur des Konferenzsystems zu machen. Dies ist eine große Veränderung und würde ein ADR rechtfertigen.Tabelle I-1 ist ein Beispiel für ein ADR, das vom Ingenieurteam, das das Konferenzsystem besitzt, vorgeschlagen werden könnte.

Tabelle I-1. ADR001 Trennung der Teilnehmer vom alten Konferenzsystem

Status	Vorgeschlagene
Kontext	Die Eigentümer der Konferenz haben zwei neue wichtige Funktionen für das aktuelle Konferenzsystem angefordert, die ohne Unterbrechung des aktuellen Systems implementiert werden müssen. Das Konferenzsystem muss weiterentwickelt werden, um eine mobile Anwendung und eine Integration mit einem externen CFP-System zu unterstützen. Sowohl die mobile Anwendung als auch das externe CFP-System müssen in der Lage sein, auf die Teilnehmer zuzugreifen, um die Benutzer bei dem Drittanbieterdienst anzumelden.
Entscheidung	Wie in Abbildung I-4 dargestellt, werden wir einen evolutionären Schritt unternehmen und die Komponente Attendee in einen eigenständigen Dienst aufspalten. Dies ermöglicht eine API-First-Entwicklung für den Attendee-Dienst und den Aufruf der API aus dem bestehenden Konferenzdienst. Dadurch wird auch die Möglichkeit geschaffen, einen direkten Zugriff auf den Attendee-Dienst zu entwickeln, um dem externen CFP-System Benutzerinformationen bereitzustellen.
Konsequenzen	Der Aufruf des Attendee-Dienstes erfolgt nicht außerhalb des Prozesses und kann zu einer Latenz führen, die getestet werden muss. Der Attendee-Dienst könnte zu einem "Single Point of Failure" in der Architektur werden und wir müssen eventuell Maßnahmen ergreifen, um die potenziellen Auswirkungen des Betriebs eines einzelnen Attendee-Dienstes abzumildern. Mit dem geplanten Modell mit mehreren Verbrauchern für den Attendee-Dienst müssen wir ein gutes Design, eine gute Versionierung und gute Tests sicherstellen, um versehentliche Änderungen zu vermeiden.

Einige der Konsequenzen im ADR sind ziemlich wichtig und müssen unbedingt weiter diskutiert werden. Wir werden einige der Konsequenzen auf spätere Kapitel von verschieben.

API meistern: ADR-Richtlinien

Im Rahmen von Mastering API Architecture werden wir ADR-Richtlinien bereitstellen, um wichtige Fragen zu sammeln, die du dir stellen musst, wenn du Entscheidungen zu dem behandelten Thema triffst. Entscheidungen über eine API-basierte Architektur zu treffen, kann wirklich schwierig sein, und in vielen Situationen lautet die Antwort "es kommt darauf an". Anstatt zu sagen, dass es darauf ankommt, ohne den Kontext zu kennen, helfen dir die ADR-Richtlinien dabei, zu beschreiben, wovon es abhängt, und dir bei deinen Entscheidungen zu helfen. Die ADR-Richtlinien können als Referenzpunkt verwendet werden, zu dem du zurückkehren oder den du vorlesen kannst, wenn du vor einer bestimmten Herausforderung stehst. Tabelle I-2 gibt einen Überblick über das Format der ADR-Leitlinien und darüber, was du von ihnen erwarten kannst.

Tabelle I-2. ADR-Richtlinie: Format

Entscheidung	Beschreibt eine Entscheidung, die du vielleicht treffen musst, wenn du einen Aspekt dieses Buches betrachtest.
Diskussionspunkte	Dieser Abschnitt hilft dir, die wichtigsten Diskussionen zu identifizieren, die du führen solltest, wenn du eine Entscheidung über deine API-Architektur triffst. In diesem Abschnitt verraten wir dir einige unserer Erfahrungen, die deine Entscheidung beeinflusst haben könnten. Wir helfen dir dabei, die wichtigsten Informationen für deinen Entscheidungsprozess zu finden.
Empfehlungen	Wir geben dir konkrete Empfehlungen, die du bei der Erstellung deines ADR berücksichtigen solltest, und erläutern dir, warum wir eine bestimmte Empfehlung aussprechen.

Zusammenfassung

In dieser Einführung haben wir mit der Fallstudie und dem Ansatz, den wir bei der Diskussion über API-gesteuerte Architekturen verfolgen werden, eine Grundlage geschaffen:

• Architektur ist eine endlose Reise und APIs können eine wichtige Rolle dabei spielen, sie weiterzuentwickeln.

• APIs sind eine Abstraktion der Implementierung und können entweder im Prozessoder außerhalb des Prozesses sein. Oft finden sich Architekten in der Situation wieder, sich zu APIs außerhalb des Prozesses zu entwickeln, worauf sich dieses Buch konzentriert.

• Die Fallstudie zur Konferenz dient dazu, Konzepte zu beschreiben und zu erläutern. In dieser Einführung hast du einen kleinen Evolutionsschritt gesehen, um den Attendee-Service auf die kommenden Geschäftsanforderungen auszurichten.

• Du hast die ersten drei Ebenen von C4-Diagrammen und ihre Bedeutung für die gemeinsame Nutzung und Kommunikation von Architektur gesehen.

• ADRs sind ein wertvolles Dokument für die Entscheidungsfindung und haben sowohl einen aktuellen als auch einen historischen Wert während der Laufzeit eines Projekts.

• Du hast die Struktur der ADR-Richtlinien gesehen, die im gesamten Buch verwendet werden, um die Entscheidungsfindung zu erleichtern.

Nachdem die Entscheidung getroffen wurde, den Attendee-Dienst aus dem Konferenzsystem herauszulösen, werden wir nun die Optionen für die Gestaltung und Spezifikation der Attendee-API untersuchen.

¹ Es soll die Benutzeroberfläche sein, die auf den Ingress-Punkt zugreift. Es ist jedoch offen für potenzielle Ausbeutung.

² Lokale Sturköpfe haben diese wahrscheinliche Erklärung angeheizt.