Eine Integrationsentwicklerin eines Partnerunternehmens öffnet das Developer Portal, findet die Bestell-API im Katalog und sieht zwölf sauber dokumentierte Endpoints. Was sie eigentlich wissen will, steht dort nicht. Sie will eine Bestellung anlegen und verfolgen, und dafür braucht sie die Reihenfolge, in der die Endpoints zusammenspielen, welcher Aufruf welches Ergebnis an den nächsten weiterreicht und was bei einer abgelehnten Zahlung zu tun ist. Nach zwei Stunden in der Endpoint-Referenz schreibt sie ein Support-Ticket mit der Frage, die der Katalog nicht beantwortet hat. „In welcher Reihenfolge rufe ich das auf?"
Einige Monate später, im selben Portal, sieht dieselbe Recherche anders aus. Neben der Bestell-API listet der Katalog drei beschriebene Workflows, darunter „Bestellung anlegen und verfolgen" mit allen Schritten, Datenübergaben und Fehlerpfaden. Die Entwicklerin liest den Ablauf in zehn Minuten, prüft ihn gegen die Testumgebung und stellt keine einzige Frage. Der Unterschied zwischen den beiden Szenen ist kein neues Produkt und keine bessere Endpoint-Dokumentation. Es ist eine zusätzliche Inhaltsart im Katalog.
Ein API-Katalog beantwortet, welche APIs existieren und was ihre Endpoints leisten. Die Reihenfolge, in der mehrere Aufrufe einen fachlichen Vorgang ergeben, beschreibt er üblicherweise nicht. Arazzo-Workflows schließen diese Lücke als maschinenlesbare Ablauf-Beschreibungen, die sich neben den OpenAPI-Specs im Katalog veröffentlichen lassen. Damit finden Konsumenten die Bausteine und gleich die Bauanleitung dazu.
Die Lücke zwischen Endpoints und Abläufen
Kataloge und Portale haben sich in den letzten Jahren stark weiterentwickelt. Ein gepflegter API-Katalog beantwortet zuverlässig, welche APIs es gibt, wer sie verantwortet und wie die einzelnen Operationen aussehen. Strukturell unbeantwortet bleibt die Frage nach dem Vorgang. Ein Partner-Onboarding, eine Bestellung mit Statusverfolgung oder eine Schadensmeldung über drei Systeme hinweg existieren im Katalog schlicht nicht als Objekte, weil seine Inhaltsarten an der einzelnen API enden.
Die Information gibt es trotzdem, nur eben woanders. Sie verteilt sich auf Wiki-Seiten, Onboarding-Folien, alte Support-Tickets und die Köpfe erfahrener Kollegen. Jede dieser Quellen veraltet in ihrem eigenen Tempo, keine wird beim API-Release mitgeprüft, und auffindbar ist am Ende keine davon. Wer den Ablauf sucht, fragt herum, und wer niemanden zum Fragen hat, wie die externe Partnerin vom Anfang, schreibt ein Ticket.
Auffällig ist, wie konstant sich diese Lücke in Support-Daten zeigt. Wenn ein Team seine wiederkehrenden Konsumenten-Fragen einmal kategorisiert, landen Fragen nach Reihenfolge und Zusammenspiel in der Spitzengruppe, deutlich vor Fragen zu einzelnen Endpoints. Die Endpoint-Dokumentation ist meist gut genug. Was fehlt, ist die Ebene darüber.
Der naheliegende Einwand lautet, dass gute Portale dafür doch Tutorials und Getting-Started-Seiten haben. Das stimmt, und diese Seiten leisten wertvolle Arbeit, aber sie teilen das Schicksal aller handgeschriebenen Ablauf-Dokumentation. Sie werden einmal verfasst, selten gegen die API geprüft und veralten unbemerkt, weil kein Test bricht, wenn die Realität sich von ihnen entfernt. Der Unterschied zur Workflow-Spec liegt weniger im Inhalt als in der Prüfbarkeit. Ein Tutorial behauptet einen Ablauf, eine ausgeführte Spec belegt ihn.
Workflows als eigene Inhaltsart im Katalog
Mit Arazzo existiert seit 2024 ein offenes Format, das genau diese Ebene beschreibt, maschinenlesbar und versionierbar wie eine OpenAPI-Spec. Was die Spezifikation leistet, erklärt der Artikel Was ist Arazzo, und wie eine konkrete Workflow-Datei entsteht, zeigt das Praxis-Tutorial. Hier interessiert der Schritt danach, nämlich die Veröffentlichung.
Ein Workflow im Katalog verhält sich am besten wie eine API, also als eigenständiger Eintrag mit Namen, Beschreibung, Version und Eigentümer. Er verweist auf die beteiligten APIs, und diese verweisen wiederum zurück auf ihn. Wer die Bestell-API findet, sieht ihre Workflows, und wer den Bestell-Workflow findet, sieht die beteiligten APIs. Diese doppelte Verlinkung ist der eigentliche Mechanismus, der die Auffindbarkeit herstellt, denn Konsumenten steigen mal über die API ein und mal über den Vorgang.
Aus der Arazzo-Datei lässt sich mehr als nur eine Textseite generieren. Die Schritte ergeben eine visuelle Ablauf-Darstellung, die Datenübergaben werden als Verbindungen sichtbar, und die Fehlerpfade zeigen, an welchen Stellen der Vorgang verzweigt. All das entsteht aus derselben Quelle, die auch der Testrunner ausführt, und genau deshalb bleibt es aktuell, während handgepflegte Ablauf-Diagramme erfahrungsgemäß nach wenigen Monaten von der Realität abweichen.
Auch die Suche profitiert von der strukturierten Quelle. Ein Konsument, der nach „Bestellung verfolgen" sucht, findet den Workflow über dessen Titel und Beschreibung, selbst wenn er die beteiligten APIs noch gar nicht kennt. Damit dreht sich die Entdeckungsrichtung um. Bisher musste man die richtige API erraten, um den Ablauf zu finden, künftig führt der gesuchte Vorgang zur passenden API. Gerade für fachlich denkende Nutzer, von Business-Analysten bis zu Product Ownern, ist dieser Einstieg über den Vorgang der natürlichere.
Was sich für Konsumenten ändert
Aus Konsumentensicht verschiebt sich mit Workflows im Katalog vor allem der Startpunkt der Integration. Bisher beginnt sie mit Detektivarbeit über der Endpoint-Liste. Mit beschriebenen Workflows beginnt sie mit dem Nachvollziehen eines geprüften Ablaufs.
- Die Reihenfolge der Aufrufe steht fest und muss nicht aus Feldnamen und Vermutungen rekonstruiert werden.
- Die Datenübergaben sind explizit. Welcher Wert aus welcher Antwort in welchen Folgeaufruf gehört, ist Teil der Beschreibung.
- Die Fehlerpfade sind dokumentiert, inklusive der Frage, welche Schritte nach einem Abbruch in welchem Zustand zurückbleiben.
- Der Ablauf ist ausführbar. Wer ihn gegen die Testumgebung laufen lässt, weiß vor der ersten eigenen Code-Zeile, dass er funktioniert.
In Summe verkürzt das die Zeit bis zum ersten erfolgreichen Vorgang erheblich und verschiebt die Support-Last. Die Frage „in welcher Reihenfolge" verschwindet aus den Tickets, weil ihre Antwort jetzt dort steht, wo gesucht wird.
Der Kontrast lässt sich entlang der typischen Integrations-Stationen zusammenfassen.
| Station | Ohne Workflows im Katalog | Mit Workflows im Katalog |
|---|---|---|
| Ablauf verstehen | Endpoint-Liste, Wiki-Suche, Kollegen fragen | Workflow-Eintrag mit Schritten und Datenflüssen lesen |
| Reihenfolge prüfen | Vermutung, Trial-and-Error gegen die Testumgebung | Beschriebenen Workflow gegen die Testumgebung ausführen |
| Fehlerfälle klären | Support-Ticket nach dem ersten Produktionsvorfall | Dokumentierte Fehlerpfade vor der Integration lesen |
| Aktualität | Wiki-Stand unbekannten Datums | Aus dem Repository synchronisiert, in der Pipeline getestet |
Welche Workflows in den Katalog gehören
Nicht jeder interne Ablauf verdient die Veröffentlichung, und eine kleine Auswahl-Logik bewahrt den Katalog vor Wildwuchs. Drei Kriterien haben sich bewährt.
Das erste ist die Konsumenten-Relevanz. Veröffentlicht wird, was Konsumenten tatsächlich nachbauen müssen, also die Vorgänge hinter den häufigsten Integrations-Szenarien. Interne Betriebs-Workflows, etwa für Datenmigrationen, gehören ins Repository, aber meist nicht ins Portal. Das zweite Kriterium ist die Stabilität. Ein Workflow, der sich wöchentlich ändert, erzeugt mehr Versions-Rauschen als Orientierung, und sein Ablauf ist möglicherweise schlicht noch nicht fertig entworfen. Das dritte ist die Vollständigkeit. Ein veröffentlichter Workflow ohne Fehlerpfade beantwortet nur die halbe Frage, und gerade die zweite Hälfte unterscheidet ihn vom Wiki.
In der Praxis ergibt das pro API selten mehr als drei bis fünf veröffentlichte Workflows, und genau diese Konzentration ist erwünscht. Der Katalog soll die Hauptwege zeigen, keine Sammlung aller denkbaren Pfade.
Hilfreich ist außerdem eine klare Zuordnung zwischen Workflow und fachlicher Domäne, analog zur Domänen-Struktur der APIs selbst. Ein Bestell-Workflow gehört in dieselbe Katalog-Kategorie wie die Bestell-API, auch wenn er daneben die Zahlungs-API berührt. Konsumenten suchen entlang ihrer fachlichen Aufgabe, und die Einordnung nach dem führenden Geschäftsobjekt entspricht dieser Suchrichtung deutlich besser als eine technische Gruppierung nach beteiligten Systemen.
Ein Plattform-Team, das wir begleitet haben, veröffentlichte als Pilot drei Workflows zu seiner meistgenutzten API im Portal. In den folgenden Wochen sank die Zahl der Onboarding-Tickets für diese API spürbar, und die verbliebenen Tickets änderten ihren Charakter. Sie fragten nicht mehr nach dem Wie des Ablaufs. Es ging nur noch um fachliche Sonderfälle, also um genau die Themen, für die ein Support-Kanal gedacht ist. Das Team wertete das als das deutlichste Signal, dass die Workflows ihre Arbeit taten.
Was sich für Anbieter-Teams ändert
Für das Team hinter der API ist die Veröffentlichung im Katalog zunächst eine Verpflichtung, und es ist ehrlich, das so zu benennen. Ein veröffentlichter Workflow ist ein Versprechen an Konsumenten, genau wie eine veröffentlichte API. Er braucht einen Eigentümer, eine Versionierung und einen Prüfmechanismus, der Abweichungen zwischen Beschreibung und tatsächlichem API-Verhalten erkennt, bevor Konsumenten sie erleben.
Die gute Nachricht ist, dass die Prozesse dafür im API-Umfeld längst existieren. Eine Arazzo-Datei lebt im Repository, wandert durch Reviews und läuft als Test in der Pipeline, alles Mechanismen, die für OpenAPI-Specs bereits etabliert sind. Die Governance dehnt sich also auf eine weitere Artefakt-Art aus, ohne dass neue Prozesse erfunden werden müssen. Wie ein Katalog im Konzernmaßstab insgesamt aktuell bleibt, über föderierte Ownership und automatischen Abgleich aus Git und CI, beschreibt der Artikel API-Katalog in großen Organisationen, und für Workflows gilt dieselbe Logik. Sie werden aus dem Repository in den Katalog synchronisiert und nicht von Hand nachgepflegt. Ihren Platz haben die Workflow-Dateien dabei in einem eigenen Repository, getrennt von den API-Repositories, weil sie eigenen Releases und Tags folgen. Der Katalog führt eine Arazzo-Datei wie eine API-Spec, mit Eigentümer, Versionen und vollständigem Audit-Trail. Gerade in regulierten Branchen ist dieser Nachweis, wer wann welchen Ablauf geändert hat, häufig die Voraussetzung dafür, Workflows überhaupt mit Partnern teilen zu dürfen.
Es gibt außerdem einen Effekt nach innen, der in Projekten überrascht. Wer seine wichtigsten Abläufe für die Veröffentlichung beschreibt, entdeckt dabei Unstimmigkeiten in den eigenen APIs, von inkonsistenten Statuswerten bis zu Lücken in den Fehlerantworten. Die Workflow-Beschreibung wirkt wie ein Review der API aus Konsumentensicht, und einige Teams beschreiben ihre Abläufe inzwischen vor dem ersten Konsumenten, genau wegen dieses Effekts.
Eine eigene Überlegung verdient die Versionierung. Ein Workflow ändert sich aus zwei Gründen, entweder weil sich eine beteiligte API ändert oder weil der fachliche Ablauf selbst umgebaut wird. Beide Fälle betreffen Konsumenten unterschiedlich stark, und ein Katalog sollte sie unterscheidbar machen. Eine korrigierte Datenübergabe ist ein Patch, ein zusätzlicher Pflichtschritt im Ablauf ist für Konsumenten eine neue Hauptversion mit Migrationsbedarf. Wer die Versionslogik seiner APIs bereits sauber führt, überträgt sie ohne großen Aufwand auf die Workflow-Einträge und erspart Konsumenten die Überraschung, dass sich ein Ablauf unangekündigt verändert hat.
Workflows, Agenten und die nächste Konsumenten-Generation
Die Integrationsentwicklerin vom Anfang bekommt absehbar Gesellschaft von einer zweiten Konsumenten-Gruppe. KI-Agenten, die Vorgänge über APIs ausführen sollen, stehen vor derselben Frage nach der Reihenfolge, nur dass sie keine Wiki-Seiten lesen und keine Tickets schreiben. Ein Katalog, der Abläufe als maschinenlesbare Workflows führt, beantwortet die Frage für beide Gruppen aus derselben Quelle.
Für deterministische Vorgänge ist die Arazzo-Beschreibung dabei die verlässlichere Grundlage als die freie Entscheidung eines Agenten zur Laufzeit, weil Reihenfolge und Fehlerpfade feststehen, während dynamische Agentic Workflows dort stark bleiben, wo echte Entscheidungsspielräume bestehen. Den größeren Rahmen, in dem sich beide Ansätze ergänzen, zeichnet der Überblick zur API-Orchestrierung. Für den Katalog heißt das schlicht, dass die Investition in beschriebene Workflows doppelt trägt, für die Menschen von heute und die Agenten von morgen.
So starten Sie mit dem ersten Workflow
Wie bei den meisten Katalog-Themen entscheidet der Anfang über die Akzeptanz, und der Anfang sollte klein sein. Ein einziger Workflow zur meistgenutzten API, sauber beschrieben, getestet und veröffentlicht, zeigt den Wert schneller als jedes Konzeptpapier. Die Kandidaten-Suche ist einfach, denn die Support-Tickets und das Wiki zeigen, welcher Ablauf am häufigsten erklärt werden muss.
Der beste Pilot-Workflow für den Katalog ist der Ablauf, zu dem Konsumenten am häufigsten Fragen stellen. Die Support-Historie der letzten Monate verrät ihn meist auf einen Blick, und die Wirkung der Veröffentlichung lässt sich anschließend direkt an den Ticket-Zahlen ablesen.
api-portal.io unterstützt diesen Weg mit einem API-Katalog, der Workflows neben den API-Specs führt, aus dem Repository synchronisiert und für Konsumenten durchsuchbar macht. Die Ablauf-Beschreibung wird damit Teil derselben Plattform, auf der Konsumenten heute schon Endpoints entdecken, Dokumentation lesen und Zugänge beantragen.
Veröffentlichen Sie als ersten Schritt den einen Ablauf, der in Ihren Support-Tickets am häufigsten auftaucht, als beschriebenen Workflow im Katalog. Vergleichen Sie die Ticket-Zahlen nach einem Quartal mit dem Stand davor, und Sie haben die Entscheidungsgrundlage für alle weiteren Workflows.