Arazzo wird oft für ein weiteres API-Format gehalten, eine Art Alternative zu OpenAPI. Diese Einordnung trifft den Kern nicht. Arazzo beschreibt keine einzelne API. Es geht um die Reihenfolge, in der mehrere API-Aufrufe zu einem fachlichen Ablauf zusammenfinden.
Eine OpenAPI-Spezifikation beantwortet die Frage, welche Endpoints eine API anbietet und wie ein einzelner Aufruf aussieht. Arazzo setzt eine Ebene darüber an. Es legt fest, in welcher Reihenfolge diese Endpoints aufgerufen werden müssen, damit am Ende ein vollständiger Vorgang entsteht, etwa ein Partner-Onboarding oder eine Bestellung über mehrere Systeme hinweg. Die OpenAPI Initiative, die auch hinter OpenAPI selbst steht, hat Arazzo im Mai 2024 veröffentlicht. Der Name ist das italienische Wort für Wandteppich und spielt darauf an, dass einzelne Aufrufe zu einem Ablauf verknüpft werden.
Arazzo ist eine offene Spezifikation der OpenAPI Initiative zur Beschreibung mehrstufiger API-Workflows. Während OpenAPI eine einzelne API mit ihren Endpoints beschreibt, definiert Arazzo, in welcher Reihenfolge Aufrufe über eine oder mehrere APIs hinweg ausgeführt werden und wie das Ergebnis eines Schritts in den nächsten einfließt. Die aktuelle Version ist Arazzo 1.1.0.
Was Arazzo beschreibt und was OpenAPI offen lässt
In den meisten Backend-Landschaften ist OpenAPI gesetzt. Jede API bringt ihre Spezifikation mit, die Endpoints sind dokumentiert, die Schemas gepflegt. Nur der Zusammenhang zwischen den Aufrufen fehlt. Eine OpenAPI-Spec führt einen Endpoint zum Anlegen einer Bestellung auf und einen weiteren zum Abfragen des Lieferstatus. Den Zusammenhang zwischen beiden beschreibt sie nicht, etwa dass der zweite Aufruf die Bestell-ID aus dem ersten benötigt.
Genau diese Lücke füllt Arazzo. Ein Arazzo-Dokument legt eine Folge von Schritten fest, bei der jeder Schritt einen API-Aufruf ausführt und seine Ergebnisse an spätere Schritte weitergibt. Der Login-Schritt liefert ein Token, der Bestell-Schritt nutzt dieses Token und liefert eine Bestell-ID, der Status-Schritt verwendet diese ID. Diese Kette lässt sich mit OpenAPI allein nicht ausdrücken, weil OpenAPI bewusst auf der Ebene der einzelnen Operation bleibt. Wer die Grundlagen der zugrunde liegenden OpenAPI-Spezifikation kennt, findet sich in Arazzo schnell zurecht, weil beide dieselbe Formsprache teilen.
Kurz gefasst beschreibt OpenAPI, was eine API anbietet, und Arazzo, wie man es in welcher Reihenfolge nutzt. Diese Unterscheidung erklärt, warum Arazzo OpenAPI voraussetzt und nicht ersetzt. Als deklarativer Ansatz gehört Arazzo zugleich in das größere Feld der API-Orchestrierung.
Wie ein Arazzo-Dokument aufgebaut ist
Ein Arazzo-Dokument besteht aus wenigen, klar benannten Bausteinen. An der Spitze steht das Feld sourceDescriptions. Dort werden die zugrunde liegenden Beschreibungen referenziert, in der Regel eine oder mehrere OpenAPI-Dateien. Darunter folgen die eigentlichen workflows. Jeder Workflow trägt eine workflowId und besteht aus einer geordneten Liste von steps.
Jeder Step ruft eine Operation auf, die über ihre operationId oder ihren Pfad in einer der Source-Beschreibungen identifiziert wird. Ein Step kann Parameter setzen, einen Request-Body mitgeben und über successCriteria prüfen, ob der Aufruf erfolgreich war. Entscheidend sind die outputs. Sie extrahieren Werte aus der Antwort und stellen sie unter einem Namen bereit, auf den spätere Schritte zugreifen. Über Ausdrücke wie $steps.authenticate.outputs.token wird das Ergebnis eines Schritts zur Eingabe des nächsten.
info:
title: Partner-Onboarding
version: 1.0.0
sourceDescriptions:
- name: partnerApi
url: ./openapi.yaml
type: openapi
workflows:
- workflowId: onboardPartner
steps:
- stepId: authenticate
operationId: createSession
requestBody:
payload:
apiKey: $inputs.apiKey
outputs:
token: $response.body#/accessToken
- stepId: createAccount
operationId: createPartner
parameters:
- name: Authorization
in: header
value: $steps.authenticate.outputs.token
outputs:
partnerId: $response.body#/id
Das Beispiel zeigt das Grundmuster. Der erste Step authentifiziert und legt das Token unter outputs ab. Der zweite Step liest dieses Token aus und setzt es als Authorization-Header. Dieser Datenfluss von Schritt zu Schritt ist der Kern jeder Arazzo-Beschreibung.
Über die einzelnen Schritte hinaus kennt Arazzo zwei weitere Mechanismen, die in echten Abläufen schnell wichtig werden. Mit successCriteria prüft ein Step anhand von Statuscode, Antwortinhalt oder regulären Ausdrücken, ob er als erfolgreich gilt. Über onSuccess und onFailure legt der Workflow fest, wie es danach weitergeht, etwa mit einem Wiederholungsversuch, einem Sprung zu einem anderen Step oder einem kontrollierten Abbruch. Auf der Ebene des gesamten Workflows beschreiben inputs die erwarteten Eingaben und outputs das Endergebnis, das der Workflow nach außen zurückgibt. Wie aus diesen Bausteinen eine vollständige, lauffähige Datei wird, zeigt Schritt für Schritt die Anleitung Arazzo in der Praxis.
Was Arazzo bewusst nicht übernimmt
Ein verbreitetes Missverständnis betrifft die Ausführung. Arazzo beschreibt einen Ablauf, führt ihn aber nicht selbst aus. Die Spezifikation legt fest, welche Schritte in welcher Reihenfolge mit welchen Datenübergaben vorgesehen sind. Welches Werkzeug diese Beschreibung dann abarbeitet, ein Testrunner, ein SDK-Generator oder ein Agent, bleibt offen und gehört nicht zur Spezifikation.
Diese Trennung ist gewollt. Arazzo hält sich aus Themen heraus, die eine Laufzeitumgebung verantwortet, etwa langlaufende Retry-Strategien, das parallele Ausführen vieler Workflows oder das Persistieren von Zwischenständen über Stunden hinweg. Arazzo bleibt eine Beschreibung und ist dadurch portabel zwischen verschiedenen Werkzeugen.
Arazzo ist eine Beschreibungssprache für API-Workflows, keine Ausführungsumgebung. Die Spezifikation legt Schritte, Reihenfolge und Datenübergaben fest, überlässt das tatsächliche Ausführen aber dem jeweiligen Werkzeug, etwa einem Testrunner oder einem Agenten.
Wofür Arazzo in der Praxis genutzt wird
Der häufigste Einstieg in Arazzo führt über die Dokumentation. Viele Teams beschreiben ihre wichtigen Geschäftsprozesse heute in Form von Prosa, ergänzt um ein paar Beispiel-Requests in einem Wiki. Solche Beschreibungen veralten schnell und lassen sich nicht prüfen. Eine Arazzo-Spec macht denselben Ablauf maschinenlesbar und damit testbar.
Daraus ergeben sich mehrere praktische Anwendungen, die meist aufeinander aufbauen.
- Mehrstufige Abläufe wie ein Partner-Onboarding über drei oder vier Endpoints werden präzise festgehalten, statt in Fließtext umschrieben zu werden.
- Aus derselben Spec lassen sich End-to-End-Tests generieren, die genau die Reihenfolge und die Datenübergaben prüfen, die der Workflow vorsieht.
- Tutorials und SDK-Beispiele bleiben konsistent mit der tatsächlichen Aufruffolge, weil sie aus einer gemeinsamen Quelle stammen.
- KI-Agenten erhalten eine verlässliche Vorlage für Abläufe, die deterministisch bleiben müssen und keinen Interpretationsspielraum vertragen.
Wir haben ein Projekt bei einer größeren Versicherung begleitet, in dem für den Schadensmeldungs-Prozess eine vierzehn Seiten lange Wiki-Beschreibung existierte, die über mehrere APIs führte. Niemand wusste verlässlich, ob sie noch stimmte. Nachdem der Ablauf als Arazzo-Workflow beschrieben war, ließ sich derselbe Prozess als automatischer Test fahren. Drei Abweichungen zwischen Dokumentation und tatsächlichem Verhalten fielen dabei innerhalb eines Nachmittags auf.
Was vielen Teams an dieser Stelle zum ersten Mal auffällt, ist eine unangenehme Eigenschaft der eigenen Dokumentation. Solange ein Ablauf nur in Prosa existiert, lässt sich kaum feststellen, ob er noch der Realität entspricht. Erst die ausführbare Spec macht den Unterschied zwischen dokumentiert und tatsächlich korrekt sichtbar.
Arazzo und KI-Agenten
Arazzo wird 2026 vor allem im Zusammenhang mit KI-Agenten häufiger genannt. Der Grund steckt im Wort deterministisch. Ein Agentic Workflow lässt ein Sprachmodell zur Laufzeit entscheiden, welches Tool als Nächstes sinnvoll ist. Das ist mächtig, wenn der Ablauf wirklich variabel ist. Für viele Geschäftsprozesse ist diese Flexibilität jedoch ein Risiko, weil die Reihenfolge eben feststehen soll.
Hier ergänzen sich beide Ansätze. Wo ein Ablauf fest definiert ist, beschreibt Arazzo ihn als verlässliche Vorlage, die ein Agent ausführt, ohne die Reihenfolge selbst erfinden zu müssen. Wo echte Entscheidungsspielräume bestehen, bleibt der agentische Ansatz im Vorteil. Die Arbeit an AI-Ready APIs und die Arbeit an Arazzo-Workflows greifen deshalb ineinander, weil beide dasselbe Ziel verfolgen, nämlich APIs für maschinelle Konsumenten zuverlässig nutzbar zu machen. Nicht jeder mehrstufige Ablauf braucht ein Modell, das mitdenkt. Häufig braucht er schlicht eine Spezifikation, die festhält, was ohnehin feststeht.
Was Version 1.1 verändert
Seit dem ersten Release hat Arazzo einen ruhigen, aber stetigen Weg eingeschlagen. Version 1.0.0 erschien im Mai 2024, ein Patch 1.0.1 folgte im Januar 2025. Die aktuelle Version 1.1.0 bringt drei Erweiterungen, die den Einsatzbereich spürbar vergrößern.
| Neuerung in 1.1.0 | Was sie ermöglicht |
|---|---|
| AsyncAPI-Support | sourceDescriptions akzeptiert neben OpenAPI- und Arazzo-Dokumenten auch AsyncAPI-Beschreibungen. Steps senden oder empfangen Nachrichten, inklusive Correlation-Identifiern und Timeouts, und reichen so über rein synchrone REST-Aufrufe hinaus. |
| Verkettete Workflows | Ein Step ruft einen anderen Workflow auf und übergibt ihm über ein explizites Mapping Eingaben. Größere Abläufe entstehen dadurch aus kleineren, wiederverwendbaren Workflows. |
| Selector Object | Feingranulare Datenextraktion aus strukturierten Antworten über jsonpath, xpath oder jsonpointer. Damit lassen sich auch Werte aus tief verschachtelten oder aus XML-Antworten sauber herausziehen. |
Die AsyncAPI-Unterstützung verdient dabei die meiste Aufmerksamkeit, weil sie Arazzo von einer reinen REST-Beschreibung zu einer Sprache für gemischte Architekturen erweitert. Ein Workflow kann jetzt einen synchronen Aufruf absetzen und im nächsten Schritt auf ein eintreffendes Event warten.
Die Neuerungen der Version 1.1.0 behandelt der Artikel Was ist neu in Arazzo 1.1 im Detail. Wer den Überblick behalten will, welche Funktionen in welcher Version dazugekommen sind, sollte die Releases der OpenAPI Initiative im Blick behalten, weil sich die Spezifikation weiterentwickelt.
Was das für Teams bedeutet
Sobald Arazzo eingeführt wird, stellt sich eine organisatorische Frage, die zunächst banal wirkt. Wem gehört die Workflow-Spezifikation? Eine Arazzo-Datei beschreibt einen Ablauf, der oftmals über mehrere APIs und damit über mehrere Team-Grenzen hinweg führt. Die zugrunde liegenden OpenAPI-Specs haben klare Eigentümer, der Workflow darüber hat häufig keinen.
In der Praxis bewährt es sich, die Arazzo-Datei beim Team des fachlichen Prozesses zu verorten und in einem eigenen Repository zu führen, versioniert wie eine API-Spec. Wird der Workflow stattdessen in einem Wiki oder einer isolierten Testumgebung gepflegt, verliert er denselben Bezug zur Realität, den die alte Prosa-Dokumentation schon hatte. Arazzo entfaltet seinen Wert erst dann, wenn jede Änderung am Ablauf auch in der Spec landet und denselben Review durchläuft wie der Code. Das eigene Repository ist dabei kein Selbstzweck. Ein Workflow ist ein eigenständiges Asset mit eigenen Releases und Tags, und diese Versionierung bleibt nur sauber, wenn sie sich nicht mit den Release-Ständen einer einzelnen API vermengt.
Der schnellste Einstieg
Der direkteste Weg zu Arazzo führt über den eigenen Bestand. Nehmen Sie einen mehrstufigen Ablauf aus Ihrer heutigen Wiki-Dokumentation, etwa ein Partner-Onboarding über drei Endpoints, und beschreiben Sie ihn als Arazzo-Workflow.
Häufige Fragen zu Arazzo
Nein. Arazzo setzt OpenAPI voraus und referenziert OpenAPI-Dokumente in seinem Feld sourceDescriptions. OpenAPI beschreibt die einzelnen Endpoints einer API, Arazzo beschreibt die Reihenfolge der Aufrufe über eine oder mehrere APIs hinweg. Beide Spezifikationen stammen von der OpenAPI Initiative und sind dafür gedacht, gemeinsam verwendet zu werden.
Das hängt davon ab, ob Ihre Konsumenten mehrere Endpoints in einer festen Reihenfolge aufrufen müssen. Für eine API, die überwiegend einzeln genutzt wird, bringt Arazzo wenig. Sobald ein Onboarding, eine Buchung oder ein Bezahlvorgang mehrere Aufrufe mit Datenübergaben kettet, macht eine Arazzo-Beschreibung diesen Ablauf prüfbar und für Konsumenten nachvollziehbar.
Arazzo ist eine Beschreibungssprache, keine Ausführungsumgebung. Es legt fest, wie ein Ablauf über APIs aussieht, schreibt aber nicht vor, welche Engine ihn ausführt. BPMN modelliert fachliche Geschäftsprozesse meist auf einer höheren, organisatorischen Ebene. Arazzo bleibt nah an den konkreten API-Aufrufen und ihrer technischen Datenübergabe.
Rund um Arazzo ist seit dem ersten Release ein wachsendes Ökosystem entstanden. Es gibt Editoren zum Verfassen der Workflows, Validatoren zum Prüfen der Spezifikation und Testrunner, die einen Arazzo-Workflow gegen eine laufende API ausführen. Weil die Spezifikation offen ist und von der OpenAPI Initiative gepflegt wird, lassen sich diese Werkzeuge frei kombinieren.
Nein. Der Nutzen für Agenten ist 2026 ein wichtiger Treiber, aber Arazzo entstand zuerst für Dokumentation, Testing und konsistente Beispiele. Auch Teams ohne jede Agenten-Ambition profitieren davon, mehrstufige Abläufe maschinenlesbar und testbar festzuhalten.
Arazzo-Dokumente werden in YAML oder JSON verfasst, genauso wie OpenAPI-Dokumente. Die Formsprache ist bewusst an OpenAPI angelehnt, sodass sich Teams, die OpenAPI kennen, schnell zurechtfinden. Eine Arazzo-Datei wird wie eine API-Spec versioniert und am besten in einem eigenen Repository gepflegt. Als eigenständiges Asset hat ein Workflow eigene Releases und Tags, die getrennt von den API-Repositories bleiben sollten, gerade wenn er über API-Grenzen hinweg geteilt wird.