API Contracts: Deine API-Spezifikationen, verknüpft mit deiner Architektur
Vor ein paar Wochen habe ich mit einem Team eine Systemarchitektur reviewt, das ein wunderschönes C4-Diagramm hatte. Container waren sauber definiert. Beziehungen hatten klare Beschriftungen. Alles sah großartig aus – bis jemand fragte: „Wie sieht die API zwischen dem Order Service und dem Payment Gateway eigentlich konkret aus?"
Stille. Im Diagramm stand „REST/JSON." Die OpenAPI-Spezifikation lag in einem anderen Repository. Die tatsächliche Endpunktliste befand sich auf einer Notion-Seite, die seit dem Weggang des letzten Praktikanten nicht mehr aktualisiert worden war. Drei Quellen der Wahrheit für eine einzige API-Oberfläche, und keine davon stimmte mit den anderen überein.
Das ist absurd häufig. API-Spezifikationen gehören zu den präzisesten, maschinenlesbaren Artefakten in einer Codebasis. Doch in der Architekturdokumentation sind sie unsichtbar. Man bekommt eine Box, einen Pfeil und ein Protokoll-Label. Der eigentliche Contract – die Endpunkte, die Schemas, die Felder – lebt irgendwo ganz anders.
Wir haben API Contracts gebaut, um das zu lösen. Deine API-Spezifikationen leben jetzt innerhalb deiner Architektur, verknüpft mit den Elementen, die sie implementieren und konsumieren.
Vier Protokolle, ein Zuhause
Moderne Systeme sprechen selten nur ein einziges Protokoll. Deine öffentliche API ist REST, deine internen Services kommunizieren über gRPC, und dein Frontend ruft Daten über GraphQL ab. Jedes hat sein eigenes Spec-Format, sein eigenes Tooling, sein eigenes Dokumentations-Ökosystem.
Archyls API Contracts unterstützen alle vier:
OpenAPI / Swagger — Importiere deine OpenAPI 3.x- oder Swagger 2.0-Spezifikationen und erhalte einen interaktiven Referenz-Viewer auf Basis von Scalar. Endpunkte werden gruppiert, Parameter dokumentiert, Schemas sind aufklappbar. Es ist dieselbe Erfahrung, die du von einem dedizierten API-Dokumentationstool kennst – eingebettet direkt in deinen Architektur-Workspace.
gRPC / Protocol Buffers — Füge deine .proto-Definitionen ein oder synchronisiere sie. Der Viewer rendert Services, Methoden, Message Types und Enums mit Syntax-Highlighting und korrekter Einrückung. Kein mühsames Durchsuchen von Proto-Dateien mehr, um zu verstehen, was ein Service exponiert.
GraphQL — Importiere dein Schema und erkunde Types, Queries, Mutations und Subscriptions. Und wenn du Server-Endpunkte konfiguriert hast, bekommst du einen vollständigen GraphiQL Playground – schreibe Queries, führe sie gegen deine tatsächliche API aus und erkunde das Schema interaktiv, ohne Archyl zu verlassen.
AsyncAPI — Definiere deine ereignisgesteuerten APIs mit AsyncAPI-Spezifikationen. Der Viewer rendert Kanäle, Operationen, Message-Schemas und Server-Bindings mit vollständiger Syntax-Hervorhebung. Ob du Kafka, RabbitMQ, NATS oder WebSockets verwendest — AsyncAPI-Contracts dokumentieren, welche Events deine Services produzieren und konsumieren.
Import aus Git oder direktes Einfügen
API-Spezifikationen ändern sich. Ein Endpunkt wird hinzugefügt, ein Feld wird als deprecated markiert, eine neue Version wird ausgeliefert. Wenn deine Dokumentation manuelles Copy-Paste erfordert, um aktuell zu bleiben, wird sie nicht aktuell bleiben.
Deshalb unterstützen API Contracts zwei Quellmodi:
Git Sync verbindet deinen Contract mit einer Spec-Datei in einem Repository. Verweise auf deine openapi.yaml, deine service.proto, dein schema.graphql oder deine asyncapi.yaml, und Archyl ruft den Inhalt direkt ab. Wenn sich die Spec upstream ändert, klicke auf Sync und der Contract wird aktualisiert. Das funktioniert mit jedem Git-Anbieter, den Archyl unterstützt – GitHub, GitLab, Bitbucket, Azure DevOps und selbst gehostete Instanzen.
Manuell ist für Teams, die ihre Specs nicht in Git verwalten, oder für schnelles Prototyping. Füge den Spec-Inhalt direkt ein und bearbeite ihn vor Ort. Nützlich, um einen Contract zu entwerfen, bevor der Service existiert, oder um eine Spec von einer Drittanbieter-API zu importieren, die du nicht kontrollierst.
Beide Modi unterstützen Versionierung, sodass du nachverfolgen kannst, welche Version des Contracts du dokumentierst.
Verknüpft mit deiner Architektur
Hier werden API Contracts zu mehr als einem Spec-Viewer.
Jeder Contract kann mit einem oder mehreren C4-Elementen verknüpft werden – Systemen, Containern, Komponenten oder Code-Elementen. Eine OpenAPI-Spec kann mit dem API-Gateway-Container verknüpft werden, der sie bereitstellt. Ein gRPC-Proto kann mit der Microservice-Komponente verknüpft werden, die es implementiert. Ein GraphQL-Schema kann mit dem BFF (Backend for Frontend) verknüpft werden, das es exponiert.
Diese Verknüpfungen sind bidirektional. Vom Contract aus siehst du, auf welche Architekturelemente er sich bezieht. Im Detail-Panel des Elements auf dem Diagramm siehst du, welche Contracts seine API-Oberfläche beschreiben. Wenn du mit der rechten Maustaste auf einen Container auf der Canvas klickst, kannst du Contracts direkt über das Kontextmenü verknüpfen und lösen.
Das schließt die Lücke, die ich am Anfang beschrieben habe. Wenn jemand fragt „Wie sieht die API zwischen diesen beiden Services aus?", ist die Antwort nur einen Klick entfernt. Nicht in einem anderen Tool, nicht in einem anderen Repository – direkt auf dem Diagramm.
Event-Kanäle
Ereignisgesteuerte Architekturen sind notorisch schwer zu dokumentieren. Welcher Service veröffentlicht auf welchem Topic? Wie sieht das Message-Schema aus? Wer konsumiert es?
Archyls Event-Kanäle bringen Sichtbarkeit in deine asynchrone Kommunikation. Jeder AsyncAPI-Contract macht automatisch die definierten Kanäle sichtbar — Topics, Queues, Streams — und ordnet sie den C4-Elementen zu, die Events produzieren und konsumieren.
Im Diagramm erscheinen Event-Kanäle als eigenständige Verbindungstypen, sodass sofort klar wird, welche Beziehungen synchrone API-Aufrufe und welche asynchrone Event-Flows sind. Das ist entscheidend für das Verständnis des Systemverhaltens: Ein REST-Aufruf zwischen zwei Services hat ganz andere Zuverlässigkeits- und Kopplungseigenschaften als ein Event, das an einen Message Broker veröffentlicht wird.
Du kannst Event-Kanäle auch unabhängig von AsyncAPI-Contracts erstellen — nützlich, um Legacy-Messaging-Systeme oder proprietäre Protokolle ohne formale Spezifikation zu dokumentieren.
Interaktive Viewer
Wir wollten nicht, dass Contracts bloße Textblöcke sind. Jedes Protokoll bekommt einen speziell dafür gebauten Viewer:
Der OpenAPI-Viewer rendert eine vollständig interaktive API-Referenz. Endpunkte werden nach Tags organisiert, mit aufklappbaren Request/Response-Schemas, Parameter-Dokumentation und Authentifizierungsdetails. Wenn du Server-URLs definiert hast, zeigt der Viewer diese an, damit Entwickler wissen, wohin sie Requests senden müssen. Es ist eine echte API-Dokumentationserfahrung, kein syntax-gehighlighteter YAML-Dump.
Der Protocol Buffer-Viewer rendert Proto-Definitionen mit korrekter Syntax-Einfärbung, sodass Services, RPCs und Message-Strukturen leicht zu erfassen sind.
Der GraphQL-Viewer hebt Types, Fields und Directives hervor. Und wenn du einen Server-Endpunkt konfiguriert hast, öffnet sich ein zweiter Tab mit einem vollständigen GraphiQL Playground. Du kannst Queries gegen deine Live-API schreiben und ausführen, das Schema per Introspection erkunden und Mutations testen – alles eingebettet in Archyl. Wenn deine GraphQL-API mehrere Umgebungen hat (Staging, Production), kannst du mehrere Server-Einträge definieren und zwischen ihnen wechseln.
Der AsyncAPI-Viewer rendert deine ereignisgesteuerten API-Definitionen mit Kanallisten, Message-Schemas und Server/Broker-Konfigurationen. Jeder Kanal zeigt seine Operationen (Publish/Subscribe), Payload-Schemas und Bindings — und gibt Entwicklern ein klares Bild deiner ereignisgesteuerten Kommunikationsoberfläche.
So startest du
Navigiere zu einem beliebigen Projekt und öffne den Bereich API Contracts in der Sidebar. Klicke auf „Add Contract" und wähle deinen Protokolltyp und Quellmodus.
Für Git-basierte Contracts verbindest du ein Repository (oder nutzt ein bereits mit deinem Projekt verbundenes), gibst den Dateipfad und Branch an, und Archyl ruft die Spec ab. Für manuelle Contracts fügst du den Inhalt direkt ein.
Nach dem Erstellen gehst du zum Diagramm und verknüpfst den Contract mit den relevanten C4-Elementen. Ab diesem Punkt kann jeder, der die Architektur erkundet, direkt vom Diagramm aus in die tatsächliche API-Oberfläche eintauchen.
Warum das wichtig ist
Architekturdiagramme sind mächtig, um Struktur zu zeigen – was existiert und wie Dinge zusammenhängen. Aber bei Schnittstellen waren sie schon immer schwach. Ein Beziehungspfeil mit der Beschriftung „REST/HTTPS" sagt dir fast nichts darüber, was tatsächlich zwischen zwei Services fließt. Ein Event, das auf ein Kafka-Topic veröffentlicht wird, ist noch undurchsichtiger — es sei denn, die AsyncAPI-Spec und das Kanal-Mapping befinden sich direkt dort.
API Contracts füllen diese Lücke. Sie bringen Präzision in die Pfeile. Wenn ein neues Teammitglied deine Architektur betrachtet und eine Verbindung zwischen der Mobile App und dem API Gateway sieht, kann es sofort die OpenAPI-Spec öffnen und genau verstehen, welche Endpunkte verfügbar sind, welche Datenstrukturen ausgetauscht werden und welche Authentifizierung erforderlich ist.
Das ist Architekturdokumentation, die ihren Wert verdient. Nicht weil sie jemand vorgeschrieben hat, sondern weil sie echte Fragen beantwortet, die jeden Tag auftauchen.
Du nutzt Archyl bereits für deine Architektur? Entdecke das API Contracts Feature in deinem Projekt. Neu auf der Plattform? Erfahre mehr über das C4-Modell und wie KI-gestützte Discovery dein Architekturdiagramm automatisch generieren kann.