APIs

Einführung

APIs sind ein zentrales Mittel, um Funktionalität und Daten zwischen Anwendungen bereitzustellen und zu konsumieren.

Um Abhängigkeiten und Datenflüsse in der Anwendungslandschaft zu verstehen, sollten APIs explizit und konsistent modelliert werden.

Dieses Pattern beschreibt einen leichtgewichtigen Ansatz zur API-Modellierung in ADOIT mit ArchiMate. Der Fokus liegt auf API-Eigentümerschaft, Konsum und ausgetauschten Geschäftsinformationen, während technische Implementierungsdetails und zusätzliche Modellierungskonstrukte bewusst vermieden werden.

Der Ansatz stellt einen bewussten Kompromiss zwischen Modellierungsdetail und Modellierungsaufwand dar. Statt jede technische Interaktion und jeden Datenfluss explizit zu dokumentieren, erfasst das Pattern die Informationen, die für Transparenz und Analyse auf Architekturebene erforderlich sind.

Designprinzip

APIs explizit machen und Eigentümerschaft klarstellen

Aus Sicht der Enterprise Architecture sollte die API-Modellierung deutlich machen, welche Applikationskomponenten verbunden sind und welche geschäftsrelevanten Daten zwischen ihnen ausgetauscht werden.

Die explizite Modellierung von APIs macht diese Abhängigkeiten sichtbar und unterstützt Integrations-Transparenz, Abhängigkeitsanalyse und Impact Bewertung.

Um architektonische Erkenntnisse mit dem Modellierungsaufwand in Balance zu halten, verwendet dieses Pattern eine kleine Menge an ArchiMate-Elementen und -Beziehungen. Die vorherrschende Richtung des Datenflusses wird aus der Anbieter-Konsumenten-Struktur abgeleitet und nicht durch zusätzliche Beziehungen modelliert.

Modellierungsstruktur

• APIs als Applikationsschnittstellen

  Jede API wird als Applikationsschnittstelle modelliert.

  Die Applikationsschnittstelle:

  • repräsentiert die API, über die eine Applikationskomponente Funktionalität und Daten für andere Anwendungen bereitstellt,
  • bietet eine stabile architektonische Repräsentation der API,
  • bleibt unabhängig von technischen Implementierungsdetails.

  APIs werden nicht implizit über direkte Verbindungen von Komponente zu Komponente modelliert.

• API-Eigentümerschaft über Applikationskomponenten

  Jede API sollte eine eindeutig identifizierte bereitstellende Applikationskomponente haben.

  Die bereitstellende Applikationskomponente komponiert die Applikationsschnittstelle.

  Der Anbieter ist aus organisatorischer und Management-Sicht für den Lebenszyklus und die Weiterentwicklung der API verantwortlich.

  Applikationskomponente → Komposition → Applikationsschnittstelle

• API-Konsum explizit machen

  Anwendungen, die eine API konsumieren, sind explizit mit der Applikationsschnittstelle verbunden.

  Die Applikationsschnittstelle dient der konsumierenden Applikationskomponente.

  Konsumenten verbinden sich daher mit der API und nicht direkt mit der bereitstellenden Applikationskomponente.

  Applikationsschnittstelle → Dienen → Applikationskomponente

  Dies unterscheidet klar zwischen Anbieter und Konsumenten.

• Hauptkonvention für Datenflüsse

  Um die Modellierung leichtgewichtig zu halten, wird die vorherrschende Richtung des Datenflusses aus der Anbieter-Konsumenten-Struktur abgeleitet:

  Bereitstellende Applikationskomponente → Komposition → Applikationsschnittstelle → Dienen → Konsumierende Applikationskomponente

  Die Applikationskomponente, die die API komponiert, gilt als Anbieter und primäre Quelle der relevanten Daten. In diesem Pattern gilt sie auch aus organisatorischer und Management-Sicht als für die API verantwortlich, einschließlich Lebenszyklus und Weiterentwicklung.

  Applikationskomponenten, die von der API bedient werden, gelten als Konsumenten der Daten.

  Diese Konvention vereinfacht die tatsächliche technische Kommunikation bewusst. APIs können Anfragen, Antworten und Informationen in beide Richtungen umfassen. Diese einzelnen Flüsse werden nicht separat modelliert.

  Das Pattern repräsentiert daher den vorherrschenden geschäftsrelevanten Datenfluss und nicht jede technische Interaktion. Das liefert ausreichend Information für Abhängigkeits- und Impact-Analysen auf Architekturebene und hält Modellierungs- und Pflegeaufwand niedrig.

• Ausgetauschte Daten über Geschäftsobjekte

  Die über eine API ausgetauschten geschäftsrelevanten Informationen werden mit Geschäftsobjekten dargestellt.

  Geschäftsobjekte beschreiben sinnvolle Geschäftsinformationen und nicht technische Payload-Schemas und können über mehrere APIs wiederverwendet werden.

  Applikationsschnittstelle → Zugriff → Geschäftsobjekt

  Zusammen mit der Anbieter-Konsumenten-Konvention wird so erkennbar, welche Geschäftsinformationen primär über die API bereitgestellt werden und welche Anwendungen sie konsumieren.

• Laufzeitunterstützung über Systemsoftware

  Wo relevant, können API-Laufzeitplattformen wie API-Gateways oder Container-Plattformen als Systemsoftware modelliert werden.

  Systemsoftware dient der Applikationsschnittstelle.

  Laufzeitunterstützung impliziert keine API-Eigentümerschaft.

  Systemsoftware → Dienen → Applikationsschnittstelle

  Die Modellierung der Laufzeit ist optional und sollte nur ergänzt werden, wenn diese Information architektonischen Mehrwert bietet.

• Technische Details als Attribute

  Technische Details wie:

  • Protokoll,
  • synchrones vs. asynchrones Verhalten,
  • Sicherheitsmechanismen,
  • Links zur Dokumentation,

  werden als Attribute erfasst und nicht als zusätzliche Modellelemente.

  Endpunkte, Methoden, Payload-Formate und einzelne Request-/Response-Nachrichten liegen außerhalb des Umfangs dieses Patterns.

Resultierendes Modellierungsmuster (kompakt)

• Kernmuster

  Bereitstellende Applikationskomponente → Komposition → Applikationsschnittstelle (API) → Dienen → Konsumierende Applikationskomponente

  Applikationsschnittstelle → Zugriff → Geschäftsobjekt

  Die Kernstruktur impliziert den vorherrschenden Informationsfluss: Anbieter → API → Konsument

• Optionale Laufzeitinformationen

  Systemsoftware → Dienen → Applikationsschnittstelle

Do / Don't - API-Modellierung

• Do

  • Jede architekturrelevante API explizit als Applikationsschnittstelle modellieren
  • Eine eindeutige bereitstellende Applikationskomponente zuweisen
  • API-Konsumenten explizit machen
  • Geschäftsrelevant ausgetauschte Informationen mit Geschäftsobjekten modellieren
  • Die Struktur Anbieter → API → Konsument nutzen, um den vorherrschenden Datenfluss anzuzeigen
  • Technische Details als Attribute belassen
  • Laufzeitinformationen nur ergänzen, wenn sie architektonischen Mehrwert bieten

• Don't

  • Applikationskomponenten nicht direkt verbinden, wenn die API selbst architekturrelevant ist
  • APIs nicht implizit modellieren
  • Nicht jede technische Anfrage und Antwort modellieren
  • Keine zusätzlichen Elemente nur einführen, um detaillierte Datenflüsse darzustellen
  • Laufzeitunterstützung nicht mit API-Eigentümerschaft vermischen
  • Endpunkte, Methoden oder Payload-Schemas nicht modellieren

Umfang und Zielsetzung

• Dieses Pattern unterstützt:

  • Integrations-Transparenz,
  • das Verständnis von API-Anbietern und -Konsumenten,
  • das Verständnis vorherrschender Datenflüsse,
  • Abhängigkeits- und Impact-Analyse,
  • Anwendungsportfolioplanung.

• Es ist nicht vorgesehen für:

  • den Ersatz technischer API-Dokumentation,
  • die Dokumentation jedes bidirektionalen Datenaustauschs,
  • die Beschreibung detaillierter Laufzeit- oder Bereitstellungsarchitektur,
  • die Modellierung von Endpunkten, Nachrichten oder Payload-Schemas.

Wo detailliertere Analysen erforderlich sind, können zusätzliche ArchiMate-Konzepte und -Beziehungen eingeführt werden. Sie sollten für den standardmäßigen leichtgewichtigen API-Modellierungsansatz nicht erforderlich sein.