ApiCatcher-Kernfunktionen: Einführung und Einsatzszenarien

ApiCatcher erfasst und untersucht HTTP/HTTPS auf iOS, Android, macOS und Windows. Auf dem Handy läuft der Verkehr über ein lokales VPN, das Gerät muss also nicht über einen Rechner als Proxy gehen. Am Desktop wechselt man zwischen Systemproxy und TUN. TUN ist für Apps, die den Systemproxy ignorieren.

Das „Api“ im Namen kommt von der ursprünglichen Aufgabe: Ein mitgeschnittener Aufruf soll nicht nur eine Zeile in der Historie bleiben. Er soll eine API werden, mit der man weiterarbeiten kann. Zu jeder der acht Funktionen steht, welches Problem sie löst und welche Einsatzszenarien dazu passen.

Capture

Hier fängt alles an. Ist die Aufnahme an, läuft HTTP/HTTPS aus Apps und Browser über den lokalen Proxy. Nach Installation und Vertrauen des CA-Zertifikats lässt sich HTTPS im Klartext lesen. WebSocket-Handshakes und Frames bleiben ebenfalls erhalten. Frames stehen wie ein Chat untereinander, JSON wird hervorgehoben, und man kann im Payload suchen.

Was man daneben benutzt:

Zulassungs- und Ausschlusslisten nach Host. Ist die Zulassungsliste nicht leer, bleiben nur passende Hosts. Hosts auf der Ausschlussliste werden nicht aufgezeichnet. * geht, etwa *.example-api.com.
Sessions sind eine Aufnahme von Start bis Stopp. Die Historie lässt sich auf diese Session begrenzen, oder die Session wird komplett gelöscht.
Suche in URL, Request-Headern, Response-Headern, Request-Body und Response-Body. Außerdem Filter nach Methode, Protokoll, Content-Type, Statuscode und Zeitraum.
Export eines einzelnen Aufrufs als Raw, cURL oder Markdown, oder eines Stapels als HAR. Bilder, Video und Audio liegen getrennt. Range-Teile werden vor dem Export zusammengefügt.

Einsatzszenario: API-Probleme untersuchen. Die fehlgeschlagene Aktion einmal nachstellen, den Aufruf in der Historie öffnen und URL, Header und Body, die der Client wirklich geschickt hat, mit Status und Body der Antwort vergleichen. Stimmt die Anfrage nicht, liegt es am Client. Stimmt die Anfrage und die Antwort nicht, liegt es am Server. Das klärt man, bevor man weitergräbt.

Einsatzszenario: Welche APIs eine Funktion nutzt. Die Funktion einmal für jedes Geschäftsszenario durchklicken. In der Historie steht dann, welche APIs liefen und wie sich die Parameter zwischen den Szenarien unterscheiden.

Automatisch erzeugte API

Passende HTTP/HTTPS-Aufrufe werden zu API-Dokumenten, gruppiert nach Host. Eine Operation ist Methode + Host + Pfad. Spätere Aufnahmen derselben Operation ergänzen nur Felder, die noch nicht vorkamen. Vorhandene Feldnamen werden nicht überschrieben. Das Antwortbeispiel wird nur bei Status 200 aktualisiert.

Export eines ganzen Hosts, einer einzelnen API oder eines Favoritenordners nach Postman, Apifox oder als Bruno-ZIP.

Einsatzszenario: In ein API-Werkzeug exportieren. Sind die Dokumente da, exportiert man Host, einzelne API oder Favoritenordner nach Postman, Apifox oder Bruno und pflegt und teilt sie dort.

Anders als bei einem HAR-Export mit Import in Postman oder vergleichbare Tools: Die von ApiCatcher erzeugten API-Dokumente werden vollständiger, je mehr Geschäftsszenarien Ihre Aufnahmen abdecken—mit jedem weiteren Szenario kommen Felder hinzu.

Replay

Beim Replay wird ApiCatcher selbst wieder zum Client. Es nimmt einen HTTP/HTTPS-Aufruf aus der Historie, ändert bei Bedarf Query, Header oder Body, schickt ihn an den Server und zeigt Status und Antwort auf der Replay-Seite. Die App aktualisiert deshalb nicht ihre Oberfläche. Bei WebSocket verbindet man sich hier neu, schickt einen Frame von Hand und liest die Antwort.

Läuft die Aufnahme, geht das Replay durch den lokalen Proxy. Rewrite-Regeln und Skripte gelten dann, und der Aufruf erscheint wieder in der Historie.

Einsatzszenario: API-Integration. Hat das Backend die API geändert oder Logs zur Fehlersuche eingebaut, spielt man den eben aufgenommenen Aufruf in einem Schritt noch einmal ab. Ein Replay zeigt, ob der Fehler weg ist, und schickt denselben Aufruf durch die neuen Logs.

Combo-Replay

Combo-Replay legt mehrere HTTP/HTTPS-Aufrufe auf eine Fläche und führt sie nach Abhängigkeit aus. Knoten ohne gegenseitige Abhängigkeit laufen parallel. Knoten mit Abhängigkeit laufen nacheinander: Die nächste Ebene startet erst, wenn die vorherige vollständig erfolgreich war.

Vier Bearbeitungen, die ständig vorkommen:

Aktion	Wirkung
Parameter vorgeben	Query, Header und Body eines Knotens vorher festlegen
Abhängigkeit setzen	Eine Linie heißt: der nachfolgende Knoten wartet auf den vorherigen
Abhängigkeit einsetzen	Einen Wert aus der vorherigen Antwort in Header, Query oder Body der nächsten Anfrage schreiben
Ausdrücke	`${method.timestamp()}` und `${method.uuid()}` werden beim Lauf ersetzt. Gemeinsame Werte wie `${token}` trägt man auf der Ausführungsseite ein

Einsatzszenario: Aufrufkette integrieren. Der spätere Aufruf braucht etwas aus der früheren Antwort. Abhängigkeit setzen, die vorherige Antwort in die nächste Anfrage einsetzen, und in dieser Reihenfolge ausführen. Zum Beispiel hängt GET /user an POST /login, und POST /order an GET /user. In den beiden letzten landet das Token in Authorization. Die Reihenfolge ist Anmeldung, Nutzerdaten, Bestellung.

Einsatzszenario: Dieselbe API mit verschiedenen Eingaben. Dieselbe Anfrage mehrfach hinzufügen. Sollen sie nacheinander laufen, hängt man alle Knoten aneinander, nur mit Abhängigkeit, ohne Einsetzen von Werten. Jeder Knoten bekommt über die vorgegebenen Parameter seinen eigenen Body. Danach vergleicht man die Ergebnisse. Zum Beispiel die Anmeldung dreimal: gültiges Konto, falsches Passwort, leeres Passwort.

Rewrite

Rewrite ändert den Verkehr, bevor die Anfrage den Server erreicht oder bevor die Antwort zur App zurückkommt. Eine Regel ist ein Bereich plus eine Aktion. Der Bereich ist ein Host, dazu optional Pfad und Methode.

Aktionen:

Umleiten: eine Produktionsdomain auf den eigenen Rechner oder die Vorproduktion schicken.
Mock: keine echte Anfrage senden, sondern Status, Header und Body vorgeben.
Anfrage verwerfen / Antwort verwerfen: ein Senden, das nicht hinausgeht, oder einen Server, der nie antwortet.
Verzögern: die Antwort aufhalten, um Ladeanzeige und Timeout in einem langsamen Netz zu sehen.
Ändern: Header anpassen, den Body komplett ersetzen oder per regulärem Ausdruck im Body suchen und ersetzen. Den Ausdruck kann die KI aus einem Satz formulieren.

Einsatzszenario: API mocken. Das Backend ist noch nicht fertig, oder der Client soll in einen bestimmten Zustand kommen. Status und Body werden vorgegeben, ohne echten Aufruf. Zum Beispiel eine Bestellliste mit „Zahlung ausstehend“ und „abgeschlossen“: Die Oberflächen sind fertig, die Regel geht aus, sobald die API da ist.

Einsatzszenario: Antwort umschreiben. Einzelne Felder anpassen und sehen, was der Client danach tut, ohne Serverdaten anzufassen. Zum Beispiel "balance": 100 per Ausdruck durch "balance": 0 ersetzen und den Button bei leerem Guthaben ansehen.

Skripte

Ändert sich ein Wert bei jedem Aufruf, reicht eine feste Regel nicht. Dann JavaScript. Eine passende Anfrage landet in interceptRequest, die Antwort in interceptResponse. Selbst schreiben, von der KI schreiben lassen oder eine Skript-URL im lokalen Netz angeben, die das Team verteilt.

Im Skript direkt verfügbar:

crypto für MD5, SHA, HMAC und Base64, für Signaturen und für das Ver- und Entschlüsseln eines Bodys.
localStore, um ein Token oder anderen Zustand über Aufrufe hinweg zu halten.
httpClient, um aus dem Skript einen weiteren HTTP-Aufruf zu machen, etwa sich neu anzumelden, wenn das Token abgelaufen ist.

Einsatzszenario: Anfrage dynamisch berechnen. Signatur und Zeitstempel sind jedes Mal anders, ein fester Ersatz greift nicht. Aus dieser Anfrage berechnen und dann durchlassen. Liefert das Replay ständig 401, bildet man aus aktueller Zeit und Body ein HMAC und setzt X-Timestamp und X-Signature. Die Aufnahme muss vor dem Replay laufen, sonst wirkt das Skript auf diesen Aufruf nicht.

Einsatzszenario: Body ver- und entschlüsseln. Interne Systeme verschlüsseln den Body oft zusätzlich zum HTTPS. Nach dem Öffnen von TLS sieht man immer noch Geheimtext. Das Skript verschlüsselt vor dem Senden und entschlüsselt nach der Antwort, damit der Klartext lesbar und änderbar ist. Zum Beispiel den Response-Body in interceptResponse entschlüsseln. Beim Replay den geänderten Klartext in interceptRequest wieder verschlüsseln. Ohne laufende Aufnahme wird das Skript nicht ausgeführt.

DNS-Täuschung

Im Produkt heißt das DNS-Zuordnung. Die Täuschung sitzt im Proxy. Weder die hosts-Datei noch das WLAN-DNS werden angefasst. Läuft die Aufnahme, überspringt eine passende Verbindung die öffentliche Auflösung und öffnet TCP direkt zur eingetragenen IP. HTTP-Host und TLS-SNI bleiben der ursprüngliche Name, die App merkt nichts. Platzhalter gehen, etwa *.apicatcher.net.

Einsatzszenario: Dieselbe Domain für Test oder Vorproduktion. Test, Vorproduktion und Produktion nutzen dieselbe Domain. Test oder Vorproduktion erreicht man, indem diese Domain auf die passende Umgebung zeigt. In der DNS-Zuordnung trägt man die IP von Test oder Vorproduktion ein. Das gilt, sobald die Aufnahme läuft. Das WLAN-DNS muss nicht jedes Mal umgestellt werden, und der DNS-Cache des Systems steht nicht im Weg.

Geplante Aufgaben

Eine Aufgabe führt ein Replay oder ein ganzes Combo-Replay nach Plan aus.

Cron hat sechs Felder, in der Reihenfolge Sekunde, Minute, Stunde, Tag, Monat, Wochentag. 0 * * * * ? ist Sekunde 0 jeder Minute. Wer die Schreibweise nicht sicher hat, lässt sie von der KI aus einem Satz erzeugen.
Eigenes Intervall: Wiederholung alle N Sekunden, optional mit Obergrenze für Anzahl oder Dauer in Minuten.

Trifft eine automatische Stoppbedingung, endet die Aufgabe. In der Ausführungshistorie stehen Dauer und Erfolgsquote. Auf dem Handy läuft die Aufgabe nur, solange die Aufnahme an ist. Am Desktop reicht es, dass die App offen ist.

Einsatzszenario: Geplantes Absenden. Das Zeitfenster ist kurz, ein Klick von Hand verpasst es leicht. Eine Anfrage oder ein Combo-Replay im Abstand automatisch senden und anhand der Antwort stoppen. Zum Beispiel wenige Sekunden vor einem Flash-Sale jede Sekunde eine Bestellung. Stopp, wenn code 200 ist oder der Body Kauf oder Sale-Ende meldet.

Einsatzszenario: Geplante Überwachung. Dieselbe API im festen Takt aufrufen und sehen, ob sie antwortet und ob sie langsamer wird. Ein Health-Check mit Cron 0 * * * * ? läuft einmal pro Minute. Ohne automatischen Stopp, und den P95 liest man in der Historie.

Einsatzszenario: Geplante Regression. Ein fertiges Combo-Replay nach Plan wiederholen und prüfen, ob die Ergebnisse noch zur Erwartung passen. Dieselbe API im Combo-Replay mehrfach anlegen und auf jedem Knoten eine andere Eingabe vorgeben. Diese Knoten sind die Testfälle. Das Combo einmal pro Woche laufen lassen. Brauchen die Aufrufe zuerst eine Anmeldung, legt man genau eine Login-Anfrage als gemeinsamen Vorgänger aller anderen an. Die übrigen Anfragen laufen dann nur parallel zueinander.

Die einzelnen Schritte stehen in der Dokumentation: Handbuch, Rewrite, Skripte, Combo-Replay, Geplante Aufgaben.

Die genannten Funktionen sind nicht alles, was ApiCatcher kann. Mehr erfahren Sie auf der offiziellen Website. Die Einsatzszenarien in diesem Artikel schränken die Anwendung nicht ein; sie zeigen, welche Probleme wir mit jeder Funktion zuerst lösen wollten.