Aktualisierung aus der Quelle

Eine API-Spezifikation lebt. Ein erneuter Import mit vollständigem Überschreiben würde Ihre Anpassungen verlieren; ein erneuter Import daneben würde ein Duplikat erzeugen. Restorm macht die dritte Sache: Es berechnet das Delta.

Wie es funktioniert

Jeder erfolgreiche Import speichert einen Fingerabdruck der Quelle im erstellten Variablenordner. Die Schaltfläche Aktualisieren des Ordners ruft die Quelle ab, vergleicht die Fingerabdrücke und wendet die Unterschiede an, statt bei null anzufangen:

• neue Operationen werden hinzugefügt, an der Stelle, an der sie ein neuer Import platziert hätte;
• bei geänderten Operationen werden die Parameter um das ergänzt, was die Spezifikation hinzufügt;
• Operationen, die die Spezifikation als veraltet markiert, werden gekennzeichnet und erscheinen abgeblendet im Baum;
• aus der Quelle verschwundene Operationen werden als entfernt gekennzeichnet und erscheinen durchgestrichen — sie bleiben ausführbar und werden nie gelöscht;
• Ihre Änderungen bleiben erhalten: Name, Methode, URL und eingegebene Werte werden nie überschrieben.

Das Prinzip: Die Spezifikation hat die Hoheit über das, was sie beschreibt, Sie haben die Hoheit über den Rest.

Der vollständige Ablauf — wo sich die Schaltfläche befindet, was der Assistent vor dem Anwenden zeigt, was mit der Dokumentation passiert — ist beschrieben in Zugriff auf und Aktualisierung der Dokumentation einer importierten API.

Nur für Importe per URL

Die Neusynchronisierung setzt voraus, dass Restorm die Quelle kennt. Nur Importe von einer URL aus speichern eine solche; ein Import aus einer Datei oder per Einfügen ist nicht neu synchronisierbar, selbst wenn sein Format in der Liste unten aufgeführt ist.

Neu synchronisierbare Formate

Zwölf Formate sind betroffen:

• OpenAPI 3.x
• Swagger 2.0 (dieselbe Seite wie der vorherige Eintrag, hier aber getrennt gezählt: Beide haben ihre eigene Logik der Neusynchronisierung)
• GraphQL (SDL)
• gRPC — .proto-Datei und Server-Reflexion
• SOAP / WSDL
• OData
• AsyncAPI
• Postman
• Insomnia
• Bruno
• OpenRPC
• Smithy

Nicht neu synchronisierbare Formate

HAR, cURL, PowerShell, REST Client, Thunder Client, Paw, HTTPie, RAML, WADL, Thrift, TypeSpec, API Blueprint, tRPC.

Für diese erzeugt ein neuer Import einen neuen Baum: Es liegt an Ihnen, beide zusammenzuführen, oder in einen eigenen Ordner zu importieren.

Sonderfall: gRPC per Reflexion

Eine per Reflexion importierte gRPC-Anfrage trägt eine Schaltfläche Aus Reflexion aktualisieren direkt auf ihrem Tab: Das ist der kürzeste Weg, wenn sich ein Dienst während der Entwicklung weiterentwickelt.