Vorlage Schnittstellendokumenation

Unter diesem Kapitel soll eine Zusammenfassung des Dokuments auf wenigen Seiten erfolgen.

Beispiel: Dieses Dokument enthält Ausfüllhinweise für die Erarbeitung von Schnittstellendokumentationen nach dem V-Modell XT in einer für den Kunden angepassten Fassung. Es handelt sich um Empfehlungen, die im Einzelfall in Absprache mit dem Kunden abgewandelt werden können. Abweichungen, insbesondere in der Dokumentstruktur sind jedoch in Kapitel 1.2 anzugeben und mit einer Begründung zu versehen.

Die Leseanleitung enthält Hilfen für den Leserkreis. Inhalte sind zum Beispiel

Die zentralen Ziele und Rahmenbedingungen bilden das einleitende Kapitel einer Schnittstellendokumentation. Damit wird ein inhaltlicher Einstieg in die Schnittstellendokumentation gegeben. Es werden die folgenden Themen behandelt:

Der Architekturüberblick beschreibt die angebotenen Schnittstellen und identifiziert Nachbarsysteme. Die Darstellung erfolgt rein aus fachlicher Sicht und differenziert nicht zwischen Schnittstellentechnologien. Jede angebotene Schnittstelle wird in Kapitel 3 detailliert beschrieben. Dieses Kapitel bietet somit einen fachlichen Gesamtüberblick über alle Schnittstellen. Je nach Komplexität kann das Diagramm auf Anwendungsebene oder auf Komponentenebene erstellt werden. Im Folgenden wird die Sicht auf die Aufwendungsebene beschrieben.

Der Architekturüberblick sollte knapp und klar gestaltet werden. Ein gutes Übersichtsbild listet Schnittstellen und externe Nachbarsysteme auf.

Neben dem Übersichtsbild werden die angebotenen Schnittstellen tabellarisch aufgelistet und kurz fachlich beschrieben.

Dieser Abschnitt ist ein Platzhalter, um zu verdeutlichen, dass ab hier weitere angebotene Schnittstellen mit ihren Ein- und Ausgabeparametern zu beschreiben sind.

Fachliche Datentypen gruppieren Typen und Wertebereichsangaben von Attributen. Die Datentypen werden in einem Datentypverzeichnis verwaltet. Beispiele: ISBN, Fahrgestellnummer, Aufzählungstypen.

Im Fall von trivialer Fachlichkeit (z.B. Beschreibungstexte, einfache Nummern) verzichten wir auf fachliche Datentypen und verwenden direkt die technischen Basistypen Zeichenkette, Ganzzahl, Kommazahl etc. Eigenschaften des Attributes und der Datentyp sollten voneinander getrennt werden.

Typischerweise verwenden verschiedene Anwendungen ähnliche Datentypen. Innerhalb einer Anwendungslandschaft müssen gleich benannte Datentypen auch den gleichen Inhalt haben. Ähnliche, aber inhaltlich unterschiedliche Datentypen sollten auch über die Anwendungen der Anwendungslandschaft explizit unterschiedlich benannt werden, um hier Verwirrung zu vermeiden.

Validierungsfehler werden durch fehlerhafte fachliche Bedingungen beim Eingang von Nachrichten ausgelöst. Zu einer Nachricht werden alle Validierungsfehler gesammelt und an den Aufrufer übermittelt. Die möglichen Validierungsfehler sind bei den Aufbauregeln der einzelnen Anfragenachrichten beschrieben. In diesem Kapitel sollen mindestens folgende Aspekte beschrieben werden:

Verarbeitungsfehler sind technische Ausnahmefehler, die zum Beispiel bei technischen Verarbeitungsproblemen oder einer nicht Schemakonformen-Nachricht auftreten können.

In diesem Kapitel sollen mindestens folgende Aspekte beschrieben werden:

In diesem Kapitel wird der Aufbau der Fehlernachricht beschrieben, die bei einem Validierungs- oder Verarbeitungsfehler an den Aufrufer zurückgegeben wird. Die Fehlernachricht ist als Schnittstellenentität ein Teil der Schnittstellenbeschreibung in Kapitel 3. Da in vielen Fällen die gleiche Schnittstellentität als Fehlernachricht für mehrere Schnittstellen verwendet wird, wird die Fehlernachricht zentral in diesem Kapitel beschrieben.

Das Antwortzeitverhalten von Nachbarsystemschnittstellen ist ein wichtiger Bestandteil der Schnittstellendokumentation, da es darüber Auskunft gibt, wie lange ein externes System in der Regel auf eine Antwort wartet. Oft erhält man hier Angaben wie "Antwortzeit beträgt max. 10 Sekunden". Falls das Performanz- und Antwortverhalten je Nachbarsystemschnittstelle differenziert, sollten die Angaben je Nachbarsystemschnittstelle dokumentiert werden. Die Angaben können je nach Umfang in Text- oder Tabellenform erfolgen.

Mengengerüste können sich auf Aspekte wie Benutzungshäufigkeit, zeitliche Verteilung der Benutzung, der Menge fachlicher Objekte und Datenvolumen beziehen. Zusammen mit dem Performanzverhalten stellt das Mengengerüst einen wichtigen Faktor in Leistung einer Schnittstelle dar. Zum Beispiel ist das Performanzverhalten nur dann aussagekräftig, wenn sie sich als Voraussetzung und Annahme auf ein konkretes Mengengerüst beziehen. Das Mengengerüst selbst ist auch ein wichtiger Aspekt, der für die Nutzung der Schnittstelle eine große Bedeutung besitzt.

In diesem Kapitel werden besondere Aspekte der Verfügbarkeit dokumentiert. Die Verfügbarkeit wird über einen Prozentwert gemessen, der unter Berücksichtigung von definierten Betriebs- und Wartungsfenstern angibt, wie ausfallsicher eine Anwendung sein sollte und tatsächlich ist. Dokumentiert wird die geplante Betriebszeit. Zum Beispiel wird hier angegeben, dass die Schnittstelle jeweils Montag bis Freitag von 07:00 bis 19:00 Uhr zur Verfügung steht. Alternativ wird auch einfach nur ein Prozentwert angegeben, zum Beispiel 99 %.

Das Glossar definiert die wichtigen fachlichen und technischen Begriffe und Abkürzungen des Projekts. Zudem werden häufig verwendete fremdsprachige Begriffe übersetzt und erläutert. Das Glossar klärt somit Begriffsbedeutungen und beugt Missverständnissen vor. Es erleichtert das gemeinsame Verständnis von Fachlichkeit und Technik, sowie die Einarbeitung der Projektbeteiligten. Schließlich etabliert das Glossar eine gemeinsame Sprache aller Projektbeteiligten, sowohl im Entwicklungsprojekt wie auch auf Kundenseite.

Beispielhaft ein Glossar zu den in diesem Dokument verwendeten Begriffen:

In diesem Kapitel werden alle Fehlercodes und dazugehörige Fehlertexte aufgelistet, die die Schnittstellen zurückliefern können.

In der folgenden Tabelle sind alle Fehlercodes mit den zugehörigen Fehlertexten als Nachschlagewerk aufgelistet.

Liste mit Referenzen auf weiterführende Dokumentation.