Verträge und Kompatibilität
Ein Vertrag beschreibt die Struktur, die eine API-Operation verspricht. Echo hält Methode, Pfad, Dokument und veröffentlichte Versionen zusammen. Ein Mock kann daraus Daten erzeugen. Eine Anwendung kann sich an eine Version binden und damit eine Abhängigkeit festhalten. Die Veröffentlichung eines Vertrags stellt keine API bereit und testet keine laufende API.
Erstelle und veröffentliche
Öffne Verträge in Maestro, erstelle einen Vertrag und öffne Version veröffentlichen. Füge ein Echo-Vertragsdokument ein und prüfe es vor der Veröffentlichung. Das Feld erwartet das JSON eines Echo-Dokuments, keine Beispielantwort und kein unkonvertiertes JSON Schema. Die Schemakonvertierung findest du im Editor für Mock-Routen.
Veröffentlichte Versionen sind nummerierte Momentaufnahmen. Die Bindung einer Anwendung hält die vereinbarte Version fest. Der Web-Diff zeigt geänderte Pfade, Gründe und getrennte Bewertungen für Verbraucher und Anbieter. Bereits veröffentlichter Inhalt kann eine vorhandene ältere Version zurückgeben, statt eine neue anzulegen.
Beachte die Richtung
Eine Consumes-Bindung bedeutet, dass die Anwendung die Operation aufruft. Provides bedeutet, dass sie die Operation anbietet. Der Vergleich unterscheidet Änderungen an Anfragen und Antworten und bewertet beide Seiten.
| Änderung | Verbraucher | Anbieter |
|---|---|---|
| Optionales Anfragefeld hinzufügen | Sicher | Sicher |
| Pflichtfeld zur Anfrage hinzufügen | Inkompatibel | Inkompatibel |
| Pflichtfeld zur Antwort hinzufügen | Sicher | Inkompatibel |
| Antwortfeld entfernen oder seinen Typ ändern | Inkompatibel | Inkompatibel |
| Optionales Antwortfeld hinzufügen | Bedingt | Sicher |
Das sind die Bewertungen des aktuellen Klassifikators. Ein zusätzliches optionales Antwortfeld ist bedingt inkompatibel, weil JsonUnmappedMemberHandling.Disallow unbekannte Felder ablehnt. Lies die Bedingung und Begründung im Diff. Safe bedeutet, dass auf dieser Seite keine Inkompatibilität gefunden wurde. Warning verlangt eine Prüfung, Breaking kennzeichnet Inkompatibilität und ConditionalBreaking hängt von der genannten Bedingung ab. Eine unbekannte Bewertung ist keine Freigabe.
Prüfe vor dem Akzeptieren
Verträge in Maestro erstellen, veröffentlichen und vergleichen gehört zu jedem Echo-Tarif, auch zu Free. Für die Veröffentlichung aus deinem eigenen Code brauchst du dagegen einen Anwendungsschlüssel. Neue Schlüssel werden unter Anwendungen in Maestro ausgestellt. Dazu sind Echo Pro oder Pro AI und die Berechtigung Echo/ManageHosting erforderlich, die der Organisationsadministrator in einem bezahlten Tarif standardmäßig erhält. Ein Anbieter kann über EchoContractPublicationClient aus Gapfy.Echo.Contracts veröffentlichen. Erstelle zuerst den Vertrag und die Provides-Bindung und nutze einen Schlüssel mit PublishOwnedContracts. Der Client veröffentlicht Versionen eigener Verträge. Er erstellt keine Verträge und übernimmt keine fremden Verträge.
Die Veröffentlichung ist abgeschlossen, wenn die Kompatibilitätsergebnisse zurückkommen. Eine inkompatible Bewertung macht sie nicht rückgängig. Prüfe die Unterschiede, bevor du einen Verbraucher änderst oder einen neuen Vergleichsstand akzeptierst.
Gapfy.Echo.Testing vergleicht konsumierte Verträge mit geprüften Momentaufnahmen in deinem Repository. Es kann die CI fehlschlagen lassen, wenn eine Änderung diesen Verbraucher bricht. Es testet weder die laufende API noch die von deiner Anwendung angebotenen Verträge.
Einen Antwortvertrag auf dem Desktop erstellen
Öffne eine Mock-Route und wähle den Antwortmodus Vertrag. Beginne mit einem JSON-Beispiel, prüfe die abgeleitete Struktur und kläre Mehrdeutigkeiten vor dem Speichern. Wähle für ein Feld einen unterstützten Generator und prüfe die Vorschauen mit einem repräsentativen Anfragepfad. Ein gespeichertes Beispiel ist ein Ausgangspunkt; es beschreibt nicht automatisch jede mögliche Antwort.
Füge benannte Szenarien für Fälle wie ein leeres Ergebnis oder eine abgelehnte Operation hinzu. Gib jedem Szenario ein Beispiel und wähle es aus, um die erzeugte Antwort zu prüfen. Sende X-Echo-Scenario: empty für ein Szenario namens empty; ohne diesen Header gilt die Standardantwort. Mit X-Echo-Seed lässt sich die Zufallsgenerierung wiederholen. Ein fester Seed hält Generatoren mit aktuellem Datum nicht an. Eine Route, die an eine veröffentlichte Vertragsversion gebunden ist, kann diese Version nicht direkt bearbeiten.
Modelle importieren, statt sie neu zu schreiben
Öffne mit angemeldetem Konto und Netzwerkverbindung Modelle importieren und exportieren im Vertragseditor der Desktop-App.
- Wähle C#, TypeScript, JavaScript, Java, Python oder JSON Schema.
- Füge Quellcode ein oder öffne zusammengehörige Dateien gemeinsam. Nimm referenzierte Typen auf und gib bei mehreren Typen den Wurzeltyp an.
- Wähle für C#, ob Eigenschaftsnamen camelCase verwenden sollen. Explizite JSON-Namen haben Vorrang.
- Prüfe die Konvertierungsvorschau. Lies Dokument, Schema und Diagnosen vor dem Anwenden.
- Wende die erfolgreiche Vorschau auf die Route an. Beim Schließen des Dialogs oder einem Konvertierungsfehler bleibt die Route unverändert. Eine geänderte Eingabe erfordert eine neue Vorschau.
Mit dem Beispiel der gewählten Sprache kannst du die erwartete Struktur prüfen, bevor du dein eigenes Modell importierst.
| Format | Benötigter Inhalt |
|---|---|
| C# | DTO-Typen und ihre referenzierten Typen |
| TypeScript | Interfaces, Typaliasnamen oder öffentliche typisierte Felder |
| JavaScript | Wörtliche statische Schema-Metadaten oder zugehörige TypeScript-.d.ts-Deklarationen |
| Java | DTOs mit öffentlichen Feldern oder Records |
| Python | Dataclasses mit Typannotationen |
| JSON Schema | Ein explizites Schema mit unterstützter Vertragsstruktur |
Die Konvertierung liest Quellcode, ohne ihn auszuführen. Fehlende Abhängigkeiten und nicht unterstützte Konstrukte erzeugen Diagnosen. JavaScript-Laufzeitwerte reichen nicht aus, um ein vollständiges Modell abzuleiten. Eigene Serializer, Polymorphie und rekursive Strukturen können ein explizites unterstütztes Schema benötigen. Importierte Schemas bleiben beim Bearbeiten von Beispiel oder Routenpfad erhalten; ändere ihre Struktur über den Import, statt einzelne Generatoren zu ersetzen.
Modelle für eine andere Anwendung exportieren
Wähle die Ausgabesprache und exportiere den aktuellen Vertrag. Prüfe die generierten Dateien, kopiere eine davon oder speichere das vollständige ZIP mit contract.schema.json. Dieselben sechs Formate stehen für den Export bereit. Der Export liest das aktuelle Dokument und veröffentlicht keine weitere Version.
Prüfe Diagnosen zu Zahlengenauigkeit sowie zu fehlenden und nullwertigen Feldern. Generierte Typen erzwingen nicht allein sämtliche Wertebereiche, Enum-Regeln oder Regeln für zusätzliche Eigenschaften; behalte dort eine Schemavalidierung bei, wo deine Anwendung sie benötigt. Python-Exporte enthalten from_dict und to_dict; Decimal-Werte brauchen einen geeigneten JSON-Encoder.
Nächste Schritte
Verbinde deine Anwendung über Anwendungen und Schlüssel oder nutze das Dokument für öffentliches Mock-Hosting.