Antwort.

Historisch gesehen war die Beschreibung von Schnittstellen zwischen Systemen das Vorrecht von Architekten und Integratoren und reduzierte sich oft auf den Austausch von E-Mails mit Datenstrukturen. In der Ära von SOA und insbesondere bei der Microservice-Architektur hat die Rolle des Systemanalytikers in der Formalisierung und Unterstützung von Integrationsverträgen erheblich zugenommen.

Problem

Fehlerhafte, unvollständige oder veraltete API-Schnittstellendefinitionen führen zu: Inkompatibilität von Services, erhöhtem Bug-Aufkommen, Unmöglichkeit von Änderungen ohne kaskadierende Störungen im gesamten System. In Multiservice-Projekten erreicht die Anzahl der Integrationspunkte Dutzende und Hunderte.

Lösung

Der Systemanalytiker wendet moderne Praktiken an:

Formalisierung von Verträgen durch Tools wie OpenAPI/Swagger für REST, gRPC-Protokolle, WSDL/XSD für SOAP;
Beschreibung typischer Aufruf- und Fehler-Szenarien;
Entwicklung von Ereignis-Modellen (event-driven model) für Echtzeitkommunikation;
Pflege aktueller Dokumentation und automatisierte Generierung von Verträgen;
Abstimmung von Änderungen mit den Eigentümern aller betroffenen Services.

Ein wichtiger Bestandteil ist das Führen einer korrekten Versionsverwaltung und Nachverfolgung von Änderungen an den Verträgen sowie die Integration von Testfällen zur Validierung von Interaktionen.

Schlüsselmerkmale:

Verwendung maschinenlesbarer Standards (OpenAPI/YAML).
Berücksichtigung aller Nutzungsszenarien und Fehler.
Regulierte Kommunikation zwischen den Teams verschiedener Services.

Gemeine Fragen.

Sollte der Analyst Anforderungen für die API nur vom Auftraggeber und internen Entwicklern sammeln?

Nein, es ist wichtig, alle integrierten Teams einzubeziehen und die Anforderungen externer Partner zu berücksichtigen, um Lücken oder Inkompatibilitäten zu vermeiden.

Kann man die API nur in der Übergabephase dokumentieren?

Nein, die API-Spezifikation wird noch vor der Implementierung erstellt und abgestimmt, sonst wird die Rückwärtskompatibilität in jeder Phase verletzt.

Ist die OpenAPI-Spezifikation an sich ausreichende Dokumentation für alle Austauschfälle?

Nein, OpenAPI beschreibt Strukturen, aber die Interaktionsszenarien (z.B. Aufrufreihenfolge, Ereignisabfolgen, Geschäftsfehler) muss der Analyst in der Benutzerdokumentation ausführen.

Typische Fehler und Anti-Pattern

Veraltete Dokumentationen oder "menschliche" Beschreibungen statt Spezifikationen ausgeben.
Fehlerbehandlung und implizite Szenarien nicht festhalten.
Fehlende Versionskontrolle und Nachverfolgung von Änderungen.

Beispiel aus dem Leben

Negativer Fall: Ein Logistiksystem wurde mit externen Transportdienstleistern integriert. Der Vertrag wurde nur "in Worten" beschrieben. Nach den Änderungen kam es zu massiven Integrationsausfällen und Verzögerungen.

Vorteile:

Minimale Arbeitsaufwände zu Beginn

Nachteile:

Massive Ausfälle
Dringende Nachbesserungen
Negative Reputation

Positiver Fall: Der Analyst erstellte OpenAPI mit Beispielen für Fehler/erfolgreiche Szenarien, stimmte die Versionierung ab und sammelte Feedback von allen Teams.