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- und AsyncAPI-Verträge, mit optionaler Git-Synchronisation.
Unterstützte Vertragstypen
| Typ | Format | Anwendungsfall |
|---|---|---|
| HTTP (REST) | OpenAPI 3.x (YAML/JSON) | REST-APIs, Webhooks |
| gRPC | Protocol Buffers (.proto) | Service-zu-Service RPC |
| GraphQL | GraphQL SDL (.graphql) | Query-APIs |
| Async | AsyncAPI (YAML/JSON) | Event-basierte APIs, Message Queues |
Einen Vertrag Erstellen
Manuelle Eingabe
- Navigieren Sie zu Ihrem Projekt
- Öffnen Sie den Tab API-Verträge
- Klicken Sie auf Neuer Vertrag
- Füllen Sie die Vertragsdetails aus:
- Name — Ein beschreibender Name (z.B. "User Service API")
- Typ — HTTP, gRPC, GraphQL oder Async
- Version — Semantische Version (z.B.
1.0.0) - Endpoint — Basis-URL der API
- Beschreibung — Was die API tut
- Fügen Sie den Spezifikationsinhalt im Editor ein oder schreiben Sie ihn
- Klicken Sie auf Erstellen
Git-Synchronisation
Anstatt Verträge manuell zu pflegen, können Sie sie aus einem Git-Repository synchronisieren:
- Klicken Sie auf Neuer Vertrag und wählen Sie Git als Quelltyp
- Wählen Sie ein verbundenes Repository
- Geben Sie den Dateipfad zur Spec-Datei an (z.B.
api/openapi.yaml) - Legen Sie den zu verfolgenden Branch fest (Standard ist der Hauptbranch des Repositorys)
- 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
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
- Öffnen Sie die Detailseite eines Vertrags
- Klicken Sie auf Mit Element Verknüpfen
- Wählen Sie die C4-Ebene (System, Container, Komponente oder Code)
- Wählen Sie das Zielelement
- 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)
- Link zur vollständigen Spezifikation
Server-Einträge
Jeder Vertrag kann mehrere Server-Einträge definieren — nützlich zur Dokumentation verschiedener Umgebungen oder Regionen.
| Feld | Beschreibung |
|---|---|
| URL | Die Server-Basis-URL (z.B. https://api.example.com/v1) |
| Beschreibung | Umgebung oder Zweck (z.B. "Production", "Staging") |
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
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
- Navigieren Sie zu Ihrem Projekt
- Öffnen Sie den Tab Event-Kanäle
- Klicken Sie auf Neuer Kanal
- Konfigurieren Sie den Kanal:
| Feld | Beschreibung |
|---|---|
| Name | Kanalname (z.B. "Bestellung-Erstellt-Events") |
| Richtung | produce oder consume |
| Broker-Typ | Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar oder Custom |
| Topic-Name | Der tatsächliche Topic- oder Queue-Name |
| Schema-Format | JSON Schema, Avro, Protobuf oder Text |
| Wert-Schema | Die Schema-Definition des Event-Payloads |
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