Ein System statt vier Stellen

Apifox begleitet eine Schnittstelle durch ihr ganzes Leben: Dokumentation schreiben, debuggen, mocken bevor das Backend existiert, und danach automatisierte Tests dagegen laufen lassen. Die Entwurfsentscheidung dahinter ist, dass alle vier Tätigkeiten dieselben Daten lesen. Ein Projekt pflegt eine Beschreibung einer Schnittstelle, alles Weitere leitet sich daraus ab – und genau das beseitigt das bekannte Problem zweier Systeme, die zwei Fassungen derselben API halten.

Die Zusammenfassung des Anbieters nennt vier Bereiche: API-Dokumentation, API-Debugging, API-Mock und automatisierte API-Tests. Die öffentliche SaaS-Ausgabe ist derzeit kostenlos, ohne Begrenzung bei Teammitgliedern, Funktionen, Projekten oder der Zahl der Schnittstellen.

Die Dokumentation entwerfen

Szenariotests führen eine Folge von Aufrufen als einen Ablauf aus und prüfen, ob die Daten zwischen ihnen korrekt bleiben. Assertions werden visuell gesetzt statt als Code geschrieben, Variablen lassen sich aus einer Antwort herausziehen, und mitten im Ablauf kann SQL gegen eine Datenbank laufen. Vor- und Nachskripte sind frei schreibbar, ihre Syntax ist vollständig kompatibel zu Postman-Skripten – für ein Team, das von dort kommt, bleibt der Lernaufwand gering.

Die Skripte sind nicht auf JavaScript beschränkt: javascript, java, python, php, js, BeanShell, go, shell, ruby und lua lassen sich aufrufen, ein vorhandenes Hilfswerkzeug muss also nicht in eine andere Sprache übertragen werden.

Debuggen

Die Debug-Ansicht bringt mit, was von einem Schnittstellenwerkzeug erwartet wird: Umgebungsvariablen, Vor- und Nachskripte sowie über Anfragen hinweg geteilte Cookie- und Session-Daten. Darüber hinaus prüft sie die Struktur einer Antwort gegen die Definition in der Dokumentation; ein Feld, das den Typ gewechselt hat oder verschwunden ist, wird gemeldet statt eine Woche später bemerkt.

Fälle gehören zur Schnittstelle und nicht zu einer Sitzung: Eine Schnittstelle kann mehrere Fälle mit eigenen Parametern und Erwartungen halten. Assertions, Variablenextraktion und SQL-Operationen werden auch hier visuell eingestellt, sodass Entwurf, Debugging und Test mit derselben Arbeitsweise laufen.

Mocking und automatisierte Tests

Mocking braucht keine Konfiguration: Das Werkzeug leitet plausible Daten aus der API-Dokumentation selbst ab. Eine eingebaute Mock.js-Regel-Engine erlaubt es, Regeln schon beim Definieren einer Datenstruktur zu setzen, und unterschiedliche Parameterwerte können unterschiedliche Inhalte liefern – erst das macht einen Mock zum Testen von Verzweigungen statt nur des geraden Wegs.

Automatisierte Tests nutzen die beschriebenen Szenariotests. Sie lassen sich über Apifox CLI von der Kommandozeile starten, und das ist der Grund, warum sie in kontinuierliche Integration passen: Ein Jenkins-Job oder ein beliebiger anderer Runner führt die Sammlung bei jedem Build aus.

Datenbank und erzeugter Code

Der Datenbankzugriff funktioniert in beide Richtungen: Daten lassen sich als Parameter einer Anfrage lesen und ebenso, um zu prüfen, ob eine Anfrage tatsächlich erfolgreich war – wichtig, wenn die Schnittstelle nur eine knappe Bestätigung zurückgibt und das eigentliche Ergebnis in einer Tabelle landet.

Aus einer Schnittstellen- oder Modelldefinition erzeugt das Werkzeug sowohl Fachlogik als auch Anfragecode. TypeScript, Java, Go, Swift, Objective-C, Kotlin, Dart, C++, C# und Rust gehören zu den 130 abgedeckten Sprachen und Frameworks, und eigene Vorlagen sorgen dafür, dass die Ausgabe den Architekturvorgaben eines Teams folgt.

Protokolle, Import und Export

HTTP- und HTTPS-Schnittstellen werden verwaltet, ebenso Socket-Verbindungen über TCP. GraphQL, Dubbo, gRPC und WebSocket sind als spätere Versionen angekündigt – nützlich zu wissen, wenn ein Projekt entscheidet, ob es sich auf das Werkzeug festlegt.

Exportiert wird als OpenAPI (Swagger), Markdown oder HTML. Der Import deckt OpenAPI (Swagger), Postman, HAR, RAP2, JMeter, YApi, Eolinker, NEI, RAML, DOClever, Apizza, DOCWAY, ShowDoc, apiDoc, I/O Docs, WADL und Google Discovery ab, eine vorhandene Sammlung muss also selten von Hand neu gebaut werden.

Zusammenarbeit im Team

Schnittstellendaten werden in der Cloud abgeglichen und in Echtzeit aktualisiert; das ist die Voraussetzung dafür, dass die Idee der einzigen Kopie bei mehreren Personen trägt. Rechte werden pro Team und pro Projekt verwaltet, mit Rollen für Administratoren, normale Mitglieder und nur lesende Mitglieder.

Für wen es sich lohnt

Ein Backend-Team, das Dokumentation, Debug-Sammlung und Testfälle an drei Orten pflegen musste, gewinnt unmittelbar: eine Definition, mehrere Verwendungen. Ein Frontend-Team, das auf eine noch nicht existierende Schnittstelle wartet, bekommt einen aus der Dokumentation erzeugten Mock statt eines von Hand geschriebenen Platzhalters. Und ein Team mit einer großen vorhandenen Sammlung kann sie meist importieren, statt neu anzufangen.