API-Verträge

API-Verträge ermöglichen es Ihnen, API-Spezifikationen an Ihre Architektur-Elemente anzuhängen und Dokumentation und Design synchron zu halten. Archyl unterstützt OpenAPI (REST)-, gRPC-, GraphQL-, AsyncAPI- und MCP-Verträge, mit optionaler Git-Synchronisation oder Live-Erkennung.

Unterstützte Vertragstypen

Einen Vertrag Erstellen

Manuelle Eingabe

1. Navigieren Sie zu Ihrem Projekt
2. Öffnen Sie den Tab API-Verträge
3. Klicken Sie auf Neuer Vertrag
4. Füllen Sie die Vertragsdetails aus:
   • Name — Ein beschreibender Name (z.B. "User Service API")
   • Typ — HTTP, gRPC, GraphQL, Async oder MCP
   • Version — Semantische Version (z.B. 1.0.0)
   • Endpoint — Basis-URL der API
   • Beschreibung — Was die API tut
5. Fügen Sie den Spezifikationsinhalt im Editor ein oder schreiben Sie ihn
6. Klicken Sie auf Erstellen

Git-Synchronisation

Anstatt Verträge manuell zu pflegen, können Sie sie aus einem Git-Repository synchronisieren:

1. Klicken Sie auf Neuer Vertrag und wählen Sie Git als Quelltyp
2. Wählen Sie ein verbundenes Repository
3. Geben Sie den Dateipfad zur Spec-Datei an (z.B. api/openapi.yaml)
4. Legen Sie den zu verfolgenden Branch fest (Standard ist der Hauptbranch des Repositorys)
5. Archyl ruft den Spec-Inhalt ab und hält ihn synchron

Sie können auch Glob-Patterns verwenden, um mehrere Dateien abzugleichen. Zum Beispiel wird api/**/*.yaml alle YAML-Dateien unter dem api/-Verzeichnis abgleichen.

Synchronisationsverhalten

• Specs werden beim Erstellen des Vertrags aus dem Repository abgerufen
• Verwenden Sie den Sync-Button, um manuell die neueste Version abzurufen
• Der Zeitstempel der letzten Synchronisation wird auf der Vertragskarte angezeigt

MCP-Server

MCP-Server (Model Context Protocol) stellen KI-Agenten Tools bereit — jedes mit einem Namen, einer Beschreibung und einem JSON Schema für seine Eingaben. Diese Tool-Oberfläche ist ebenfalls ein Vertrag: sie definiert, was ein Agent tun darf. Archyl dokumentiert sie als Vertragstyp MCP.

Anders als die übrigen Typen liegen die Tools eines MCP-Servers meist nicht als Datei in einem Repository — die maßgebliche Liste existiert nur zur Laufzeit, über den tools/list-Aufruf. MCP-Verträge bieten daher zwei Quellen.

Die Tool-Liste einfügen

1. Klicken Sie auf Neuer Vertrag und wählen Sie MCP
2. Belassen Sie die Quelle auf Manuell
3. Fügen Sie das tools/list-JSON des Servers ein — ein Objekt der Form { "tools": [ ... ] }
4. Klicken Sie auf Erstellen

Archyl validiert das Dokument und rendert jedes Tool.

Von einem Live-Endpunkt erkennen

Lassen Sie Archyl die Tools direkt von einem laufenden Server abrufen:

1. Klicken Sie auf Neuer Vertrag, wählen Sie MCP und als Quelle Live endpoint
2. Geben Sie die Server-URL ein und wählen Sie den Transport (HTTP oder SSE)
3. Wenn der Server Authentifizierung benötigt, wählen Sie, wohin das Token geht — ein Header (z.B. X-API-Key) oder ein Query-Parameter — und geben Sie das Token ein
4. Klicken Sie auf Tools entdecken — Archyl verbindet sich, führt den Handshake durch und listet jedes Tool und seine Parameter auf
5. Prüfen Sie die entdeckten Tools und klicken Sie dann auf Erstellen

Um die Tools später zu aktualisieren, bearbeiten Sie den Vertrag und führen Sie Tools entdecken erneut aus.

Die Erkennung läuft in Ihrem Browser, nicht auf Archyls Servern. Ihr Token verlässt nie Ihren Browser — Archyl speichert die entdeckten Tools und die Verbindungsdaten (URL, Transport, Header-/Parametername), aber niemals das Token selbst. Da der Aufruf von Ihrem Rechner ausgeht, erreicht er auch Server auf localhost oder in Ihrem privaten Netzwerk.

Die einzige Voraussetzung: der MCP-Server muss den Ursprung dieser Seite zulassen (CORS), damit Ihr Browser die Antwort lesen kann. Bei Servern, die Sie kontrollieren, ist das eine kleine Konfigurationsänderung; andernfalls nutzen Sie die Einfügen-Option oben.

Der MCP-Tool-Viewer

Jedes Tool wird mit Namen, Beschreibung und Eingabeparametern (abgeleitet aus seinem JSON Schema) angezeigt, wobei das rohe Schema je Tool verfügbar ist. Wie bei den anderen Vertragstypen ist der Viewer schreibgeschützt und spiegelt die gespeicherte Tool-Liste wider.

Verträge mit der Architektur Verknüpfen

API-Verträge werden bedeutsam, wenn sie mit den C4-Elementen verknüpft werden, die sie beschreiben. Ein Vertrag kann mit Systemen, Containern, Komponenten oder Code-Elementen verknüpft werden.

Verknüpfungen Hinzufügen

1. Öffnen Sie die Detailseite eines Vertrags
2. Klicken Sie auf Mit Element Verknüpfen
3. Wählen Sie die C4-Ebene (System, Container, Komponente oder Code)
4. Wählen Sie das Zielelement
5. Die Verknüpfung erscheint sowohl am Vertrag als auch im Detailpanel des Elements

Verknüpfte Verträge Anzeigen

Klicken Sie im Diagramm mit der rechten Maustaste auf ein beliebiges Element, um sein Detailpanel zu öffnen. Verknüpfte API-Verträge erscheinen im Abschnitt Verträge mit:

• Vertragsname und -version
• Protokolltyp-Badge (HTTP, gRPC, GraphQL, Async, MCP)
• Link zur vollständigen Spezifikation

Server-Einträge

Jeder Vertrag kann mehrere Server-Einträge definieren — nützlich zur Dokumentation verschiedener Umgebungen oder Regionen.

Der Spezifikations-Viewer

Archyl rendert Ihre API-Spezifikationen mit einem interaktiven Viewer:

• OpenAPI — Endpoints nach Tag gruppiert, mit Request/Response-Schemas, Parametern und Beispielen
• gRPC — Service-Definitionen, RPC-Methoden und Message-Typen
• GraphQL — Typen, Queries, Mutations und Subscriptions
• AsyncAPI — Channels, Messages und Schemas
• MCP — Tools, jeweils mit Beschreibung und Eingabeparametern (aus dem JSON Schema)

Der Viewer ist schreibgeschützt und spiegelt immer den aktuellen Inhalt des Vertrags wider.

Event-Kanäle

Event-Kanäle dokumentieren die asynchrone Messaging-Seite Ihrer Architektur — Kafka-Topics, SQS-Queues, RabbitMQ-Exchanges und ähnliche.

Einen Event-Kanal Erstellen

1. Navigieren Sie zu Ihrem Projekt
2. Öffnen Sie den Tab Event-Kanäle
3. Klicken Sie auf Neuer Kanal
4. Konfigurieren Sie den Kanal:

Verknüpfung mit der Architektur

Event-Kanäle folgen demselben Verknüpfungsmodell wie API-Verträge. Verknüpfen Sie einen Kanal mit den Systemen, Containern oder Komponenten, die seine Events produzieren oder konsumieren. Dies macht Nachrichtenflüsse direkt im Architekturdiagramm sichtbar.

Best Practices

Halten Sie Specs Aktuell

• Verwenden Sie Git-Sync für Specs, die in Ihrer Codebase leben
• Versionieren Sie Ihre Verträge mit semantischer Versionierung
• Aktualisieren Sie den Vertrag, wenn sich die API ändert

Verknüpfen Sie Alles

• Jeder Container, der eine API bereitstellt, sollte mindestens einen verknüpften Vertrag haben
• Verknüpfen Sie Event-Kanäle sowohl mit Produzenten als auch Konsumenten
• Nutzen Sie Verknüpfungen, um das Diagramm selbstdokumentierend zu machen

Organisieren Sie nach Service

• Ein Vertrag pro Service oder Bounded Context
• Verwenden Sie beschreibende Namen, die zu Ihrer Architektur-Benennung passen
• Nehmen Sie die API-Version in das Versionsfeld des Vertrags auf

Dokumentieren Sie Server

• Fügen Sie Server-Einträge für jede Umgebung hinzu
• Schließen Sie sowohl interne als auch externe Endpoints ein
• Halten Sie URLs aktuell, wenn sich die Infrastruktur ändert

Nächste Schritte

• Event-Kanäle — Dokumentieren Sie asynchrones Messaging
• Architektur-Änderungsanträge — Schlagen Sie Änderungen an Ihrer Architektur vor
• Release-Management — Verfolgen Sie Deployments über Ihre Systeme