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
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.
Nächste Schritte
Verbinde deine Anwendung über Anwendungen und Schlüssel oder nutze das Dokument für Remote-Mocks.