Lesezeit: 4 Minuten

API-Dokumentation jenseits der Bestandsaufnahme

Wie viel Lebenszeit haben Sie bereits verschwendet bei der verzweifelten Suche nach korrekter API-Dokumentation oder passenden Beispieldaten? Wir können sagen, dass es in der Vergangenheit öfter der Fall war als uns lieb ist und wir einige graue Haare als “Narben dieser Kämpfe” vorzuweisen haben.

Angesichts der zunehmenden Verbreitung mobiler Anwendungen und Single Page Applikationen werden immer mehr APIs für Softwaresysteme entwickelt oder bereitgestellt. Die Nutzung direkt anwendbarer APIs zur Vernetzung zwischen Anwendungen ist mittlerweile zur Norm geworden und kein kostspieliger Zusatz mehr.

Diese APIs ermöglichen nicht nur das Datenmanagement, sondern auch die Abbildung komplexer Geschäftsprozesse, die ein tiefes Verständnis der API-Nutzer erfordern. Leider ist die Dokumentation zur korrekten Anwendung dieser APIs häufig schlecht strukturiert, veraltet oder sogar fehlerhaft.

Dies führt zu hohen Aufwänden für API-Konsumenten und kostspieligen Fehlern, die sich nicht selten bis in die produktiven Systeme fortpflanzen. Hier besteht erheblicher Verbesserungsbedarf, damit die eigene Wettbewerbsfähigkeit nicht leidet!

Der Status Quo: OpenAPI und seine Grenzen

Ein etablierter Standard für die Dokumentation von HTTP-basierten APIs ist die Verwendung von Swagger bzw. OpenAPI-Dokumenten. Diese Dokumente informieren über die Existenz und mögliche Strukturen der ein- und ausgehenden Daten. Darüber hinaus können auch Fehlerverhalten und Themen wie Authentifizierungsmechanismen behandelt werden.

Ein weiterer Vorteil von OpenAPI-Dokumenten ist die Möglichkeit, über Softwaretools Quellcode zu generieren oder Schnittstellen automatisch auf ihre technische Konformität zu überprüfen.

Daher sind diese Artefakte zu Recht ein wesentlicher Bestandteil der API-Dokumentationsstrategie. Dabei spielt es keine Rolle, ob man API-First arbeitet oder die Dokumentation frisch durch Bibliotheken im Service generieren lässt.
 

Das Problem: fehlende Zusammenhänge

Auch erfahrene Entwickler und Cloud Engineers stoßen hier oft an Grenzen: Während OpenAPI hervorragend für die Dokumentation einzelner Schnittstellen geeignet ist, reicht es in komplexeren Szenarien – etwa bei der Orchestrierung mehrerer APIs oder der Abbildung von Prozessflüssen – oft nicht aus. Hier zeigt sich, dass eine erweiterte Perspektive auf die Dokumentation nötig ist.

Die in den OpenAPI-Dokumenten bereitgestellten Informationen sind wichtig, reichen aber oft nicht aus, um nicht triviale APIs korrekt zu nutzen. In vielen Fällen ist zusätzliche Dokumentation erforderlich oder, im schlimmsten Fall, muss einfach herumprobiert werden. Die Dokumentation beschreibt häufig nur, was angeboten wird, jedoch selten, was in welcher Reihenfolge wie eingesetzt werden sollte.

Ein weiteres Problem sind APIs, die verschiedene Varianten für Geschäftsprozesse anbieten oder komplexe, flexible Datenmodelle abbilden, bei denen je nach Datenlage unterschiedliche Prozessschritte durchlaufen werden müssen.

Die OpenAPI bietet über den Arazzo-Standard zwar eine Lösung zur Dokumentation von Prozessen. Diese Dokumente sind aber selten anzutreffen und die Tools unterstützen den Standard in der Regel auch nicht.

Aufgrund der Struktur und spezialisierten Darstellungsform von API-Spezifikationen im OpenAPI-Format sind diese für eine Dokumentation dieser Aspekte nicht geeignet.

Es fehlen die Zusammenhänge zwischen API-Aufrufen in Kombination mit unterschiedlichen Daten sowie die Möglichkeit, verständliche Informationen zu den einzelnen Prozessflüssen bereitzustellen.

Wenn eine Schnittstelle in mehreren Prozessen verwendet wird, können auch die Fehlerfälle variieren, die im jeweiligen Kontext auftreten. Diese Varianten in OpenAPI zu dokumentieren, führt oft zu schwer lesbaren Erklärungen, die die Nützlichkeit des Dokuments weiter verringern.

Wie wäre es, wenn… Ihre Dokumentation Prozesse abbildet und die Korrektheit durch Tests sichergestellt wäre?

Darüber hinaus gibt es auch noch weitere organisatorische Aspekte mit hoher Relevanz, die in der Dokumentation einer API geregelt werden.

• Wer sind die Ansprechpartner hinter dieser API?
• Wie kann ich mit diesen bei aufkommenden Fragen und Problemen in Kontakt treten?
• Welche Vereinbarungen und Zusicherungen seitens des API Providers gelten bei der Verwendung, wie z.B. Limits, Mengengerüste, SLAs und Verfügbarkeiten beim Zugriff, aber auch ggf. Haftungsfragen in Problemsituationen?

Standardisierung der Interaktion mit Hilfe des API Lifecycles

Wie aber kommuniziert der Anbieter einer API mit seinen Konsumenten? Hierfür hat sich ein Interaktionsmodell herauskristallisiert - der sogenannte API Lifecycle. Der API Lifecycle liefert standardisierte Antworten auf folgende Fragestellungen:

• Wie lange kann ich versichern, dass eine API-Version nutzbar ist?
• Wie veröffentliche ich Fehlerbehebungen oder zusätzliche Features, ohne die laufende Interaktion mit Konsumenten zu stören?
• Wie verhält sich ein API Provider Team im Falle von „Breaking Changes“ (=Änderungen der geltenden technischen/organisatorischen Vereinbarungen)?

Also zusammengefasst sind APIs ein Interaktionsmodell, das sogenannten soziotechnischen Systemen (Wertschöpfung bestehend aus dem Zusammenspiel von Mensch und Technik) erlaubt, ihre Zusammenarbeit zu standardisieren, ohne dabei die Unabhängigkeit/Agilität beider Parteien negativ zu beinträchtigen. APIs bieten bei richtiger Anwendung die Möglichkeit, widerstandsfähige und stabile Integrationen zu ermöglichen.

Tipp für den Einstieg: Gutes Design für den langfristigen Erfolg von API-Produkten

In einer idealen Welt würde die Dokumentation nicht nur die verfügbaren Schnittstellen umfassen, sondern sich an den Geschäftsprozessen orientieren und diese von Anfang bis Ende beschreiben. Teil dieser Beschreibung wären auch die Fehlerfälle, die in diesem Prozess an den jeweiligen Stellen auftreten können.

Mit einer prozessorientierten Dokumentation könnten Entwickler nicht nur schneller produktiv arbeiten, sondern auch Fehler vermeiden, die durch unklare oder unvollständige Informationen entstehen. Architekten könnten sicherstellen, dass komplexe Prozesse sauber modelliert und integriert werden – ohne die langfristige Wartbarkeit zu gefährden.

Ein Traum wäre es auch, wenn der dargestellte Prozess auch wirklich durch Softwaretests abgesichert wäre, so dass man sich darauf verlassen kann, dass der Prozess auch genau so funktioniert.

 

Ein klarer Prozessflow macht APIs verständlich

Eine solche Beschreibung würde es ermöglichen, besser auf Varianten einzugehen. Angenommen, man entwickelt eine E-Commerce-Anwendung, die verschiedene Bezahlarten anbietet. Einige sind sehr einfach, wie der Kauf per Vorkasse, während andere komplexer sind, weil sie individuelle Schritte beinhalten, die im jeweiligen Kontext relevant sind. So ist beim Kauf auf Rechnung ein Schufa-Check und die Adressvalidierung erforderlich, während beim Kauf mit Kreditkarte bestimmte Schritte mit dem Zahlungsabwickler umgesetzt werden müssen. Die Verwendung verschiedener Zahlungsdienstleister, je nach Zahlungsmittel, ist nicht unüblich.

Daher müssen je nach Auswahl der Zahlungsart unterschiedliche Funktionen innerhalb der verschiedenen APIs verwendet werden. Ohne eine angemessene Dokumentation wird dies zu einem Albtraum für die beteiligten Entwickler.

Des Pudels Kern

Für API-Nutzer ist es, frei nach Goethe, entscheidend, was die API im Innersten zusammenhält. Es geht nicht nur darum, welche Funktionen aufgerufen werden, sondern auch in welchem Zusammenhang und mit welchen Daten oder Parametern. Auch die Antwort ist von Interesse, deren Struktur je nach Kontext unterschiedlich ausfallen kann.

Hier ist es wichtig, aktuelle und korrekte Beispiele zu haben, um effektiv mit einer API arbeiten zu können. Veraltete Beispiele können manchmal schlimmer sein als keine! Je nachdem, wie die Dokumentation erstellt wird, sind die Beispieldaten schneller veraltet, als man die Dokumentation veröffentlichen kann.

Im obigen Beispiel wurden auch APIs von Drittanbietern angesprochen, die in einem Geschäftsprozess verwendet werden. Diese Lücke wird in vielen „service-orientierten“ Dokumentationen übersehen, da sie sich auf die eigene Schnittstelle konzentrieren und nicht auf das große Ganze.

 

Eine Lösung: Tests als Grundlage für Dokumentation nutzen

Für diese Herausforderungen gibt es eine Reihe von mehr oder weniger geeigneten Lösungen. Eine gute Lösung sollte auf Tests basieren, um zu verifizieren, dass der beschriebene Prozess mit den Beispiel-Ein- und Ausgaben auch tatsächlich funktioniert. Diese Ein- und Ausgaben sollten dann auch in der bereitgestellten Dokumentation Verwendung finden, um “Lücken” zu vermeiden. Wir wollen ja realistische Beispiele und keine angepassten JSON-Ausschnitte, die dann doch in der Realität so nicht anzutreffen sind oder genau den im Moment interessanten Aspekt nicht enthalten.

In diesem Artikel möchten wir auf eine Lösung hinweisen, die schon länger existiert, aber noch nicht die Verbreitung erfahren hat, die angemessen wäre.

Spring REST-Docs wurde Ende April 2017 mit der Version 1.2 veröffentlicht und hat mittlerweile die Version 3.0.x erreicht. Obwohl der Name es vermuten lässt, können damit nicht nur Spring-Projekte dokumentiert werden, sondern auch alle Services, die eine HTTP-Schnittstelle anbieten. In diesem Fall schreibt man die entsprechenden Tests mittels REST-Assured anstelle dem Spring-eigenen “MockMVC” und kann so die Ein- und Ausgaben extrahieren.

Dies ist auch der Ansatz, den man für die serviceübergreifende Prozessdokumentation verfolgen würde, indem man beispielsweise in einer Integrationsumgebung die Prozesstests ausführt und so vollständige und realistische Daten erhält.

Natürlich ist die Verwendung für Spring-Projekte entsprechend tiefer und effizienter, da dort analog zu Spring-Boot-Tests der Service nicht vollständig hochgefahren werden muss und man auch einzelne Bestandteile der Services mittels der MockMVC API isoliert testen kann. Das beschränkt einen zwar auf den konkreten Service, ist aber sehr effizient zu entwickeln und schnell in der Ausführung.

In der Standardkonfiguration erzwingt REST-Docs die Dokumentation der eingehenden und ausgehenden Daten und bricht den Test ab, wenn unerwartet Datenfelder hinzukommen oder fehlen. Dies führt zu einem hohen Vertrauen in die Stabilität der API und der Dokumentation, da unbeabsichtigte Änderungen oder Konfigurationsfehler schnell erkannt werden können und in der Regel auch behoben werden müssen.

Bei den Aufrufen wird immer der vollständige Request und die Response mitgeschnitten und mit einem konfigurierten Namensschema im Dateisystem abgelegt. Diese generierten „Schnipsel“ werden üblicherweise in zu schreibenden AsciiDoc oder Markdown-Dokumenten referenziert, wo der Kontext und weitere relevante Informationen für die jeweiligen Schritte textuell erklärt werden.

Da der AsciiDoc-Renderingprozess abbricht, wenn referenzierte Schnipsel fehlen, gibt es hier auch einen schnellen Feedbackzyklus, wenn zuvor dokumentierte Schnittstellen oder Prozesse/Prozessschritte wegfallen.

Hier gibt es eine Lücke in der Absicherung durch Spring RestDocs, weil veränderungen im Prozess, die einfach weitere Aufrufe hinzufügen nicht unbedingt den Testlauf mit einem Fehler beenden. Hier ist genau wie bei der Qualitätskontrolle der Dokumentation und des Quellcodes weiterhin Disziplin und wenn möglich ein Review empfehlenswert.


 

Fazit: Mit Tests angereicherte und abgesicherte Dokumentation als Schlüssel zu Effizienz und Erfolg

Eine reine Dokumentation der vorhandenen Schnittstellen ist in vielen Fällen nicht ideal und führt zu Problemen oder ineffizienter Arbeit.

Gerade komplexe Fehlerfälle oder Prozesse benötigen eine dedizierte Dokumentation, deren Korrektheit sichergestellt werden muss.

Dokumentation kann sich schnell von der Realität entfernen, wenn es keine automatisierbaren Signale gibt, die anzeigen, dass Wunsch und Wirklichkeit nicht mehr übereinstimmen.

Kleinere Änderungen, wie zusätzliche Felder, sollten mit möglichst geringem Aufwand schnell in der Dokumentation integriert werden können.

Dokumentation ist immer Aufwand, aber man sollte versuchen, mit möglichst wenig Arbeit ein korrektes Ergebnis zu erzielen, das den Zielgruppen tatsächlich hilft.

Gute API-Dokumentation ist kein Luxus – sie ist ein wesentlicher Erfolgsfaktor. Mit Tools wie Spring REST-Docs lassen sich Dokumentationen automatisiert und immer aktuell halten.

Investieren Sie die Zeit, um Ihre Dokumentationsstrategie zu überdenken:
Ihre Entwickler und Architekten werden es Ihnen danken – und Ihre Projekte werden davon profitieren.

.