Du brauchst eine Einführung in Insomnia?
Dieses Insomnia Tutorial zeigt, Dir wie Du effektiv APIs testen und debuggen kannst.
Starten wir!
Was ist Insomnia?
Dieses Programm ist eine Test-Software für eine Anwendungsschnittstellen (Application Programming Interface, API). Ein Backend-Entwickler von Software nutzt diese, um REST- / GraphQL-Anwendungsschnittstellen anzusprechen.
Die Software ermöglicht ein exaktes Vordefinieren eine Anfrage und die Schnittstelle antwortet auf diese Anfrage. Das Programm hilft bei der Fehlersuche, Reproduktion und Testen von Backend-Software.
Wenn ein normaler Browser-Nutzer eine Webseite abruft, dann führt dieser eine HTTP-GET-Anfrage aus, um eine Webseite zu erhalten. Weitere HTTP-Anfragen-Typen wie POST, PUT, DELETE
und eigene Typen sind möglich. Diese lassen sich über die Nutzung eines Browsers nicht so einfach abbilden.
Warum das Programm nutzen?
Übersichtlichkeit
Wenn Du mehrere Schnittstellen gleichzeitig testen möchtest, dann ist die Software ein Muss für Dich. Gruppiere Anfragen nach Thema, erstelle eigene Projekte für unterschiedliche Software und nutze die Historie für vergangene Anfragen.
Automatisierung
Statt jeden Request einzeln zu erstellen und abzusenden, kannst Du jegliche Konfiguration speichern und Anfragen gegen Deine API absenden. Wenn Du bei einem Release sicher gehen willst, dass alte Features / REST-Schnittstellen noch funktionieren, kannst Du diese ausführen.
Tiefe Einblicke
Nicht nur Inhalte sind relevant, sondern auf die Header-Inhalte.
Die HTTP-Header geben den Rahmen an:
- Welche Inhalte sollen wie übertragen werden?
- Welche Sicherheitsvorschriften muss der Browser beachten?
- Wie soll das Caching stattfinden?
Das Tool bietet Dir eigene Header zu erstellen und diese zu modifizieren.
Insomnia Guide
Installieren
Insomnia kannst Du auf der Hersteller Webseite als .exe herunterladen und in Windows installieren. Linux Systeme kannst Du mit Flatpak versorgen.
flatpak install flathub rest.insomnia.Insomnia
Alternativ füge in den Paketmanager apt-get die neue Software als PPA-Repo hinzu:
# Add to sources echo "deb [trusted=yes arch=amd64] https://download.konghq.com/insomnia-ubuntu/ default all" \ | sudo tee -a /etc/apt/sources.list.d/insomnia.list
# Refresh repository sources and install Insomnia
sudo apt-get update
sudo apt-get install insomnia
Erste Schritte in Insomnia
Die Software begrüßt Dich mit einem Dashboard.
Hier kannst Du Projekte anlegen oder importieren. Manche APIs geben Dir eine JSON, welche Du in die Software importieren kannst. Diese Datei importiert alle verfügbaren Anfragen mit vielen Beispielen und internen Abkürzungen und Authentifizierungsoptionen.
Erstelle zuerst ein Projekt mit einem Klick auf Create
. Wähle die Request Collection aus. Benenne das Projekt wie die API, die Du testen möchtest.
In der linken Spalte kannst Du eine neue Anfrage erstellen. Vergesse nicht, mit einem Doppelklick auf die Anfrage dieser einen sprechenden Namen zu geben. 20-mal „New Request“ bringen Dich nicht weiter.
Anfrage Konfigurieren
In der Mitte oben kannst Du statt den HTTP-GET
andere Methoden auswählen. Viele wissen nicht, dass Du auch Deine eigenen definieren kannst. In der Regel sollten diese aber für die Standardoperationen Create, Update, Read und Delete ausreichen.
Die URL kannst Du rechts davon eingeben. Diese kann auf einem einfachen String oder String mit Variablen basieren. Eine Variable ist ein Platzhalter, welche Du unter dem Button „Environments“ verwalten kannst. Ersetze die Domain durch eine Variable. Beim Umzug der API musst Du nicht dann alle Anfragen anpassen, sondern nur die Variable.
Statt die GET-Parameter in die URL zu klatschen, sieht die Software ein Formular mit den Parametern in Tab 2 unterhalb der URL-Leiste vor. Die Software baut aus der Tabelle mit dem Parameter-Namen und den Werten die vollständige URL zusammen. So behältst Du einen besseren Überblick.
Ausgabe umschalten
Sobald Du den Request absendest, siehst Du die Antwort auf der rechten Seite. Der Tab 1 ermöglicht die Ansicht als rohen Code (HTML, XML, JSON), eine formatierte Ansicht mit Highlighting und eine Browser-Darstellung (Visual Preview).
In Tab 2 siehst Du alle Antwort-Header. Diese helfen Dir Problem zu finden. Ein typischer Fehler ist ein inkorrekter MIME Typ der Antwort. Tab 3 beinhaltet die Cookies, welche die Anfrage mitgesendet hat.
… und der letzte Tab zeigt Dir den Ablauf der Anfrage. Hier siehst Du Header, Inhalte, URL usw. in der Abfolge, wie die Anwendung diese verarbeitet hat.
Mit einem Rechtsklick auf den Anfragennamen kannst Du die Anfragen kopieren, diese duplizieren oder als Terminal CURL
-Kommando kopieren. Dieses Vorgehen spart Dir eine Menge an Arbeit.
Die Authentifizierungen verstehen
Viele Anwendungsschnittstellen nutzen eine Authentifizierung, um Unternehmen und Personen zu identifizieren, Kosten zu tracken und Inhalte zu limitieren.
Tokens richtig einsetzen
Die meisten APIs arbeiten nicht nur mit einem Nutzernamen und Passwort, sondern mit Tokens und Dateien. Nach einer erfolgreichen Authentifizierung, kann die API z. B. einen temporären Token zurücksenden, mit welchen Du die API in der nächsten Stunde abfragen kannst. Kein Dritter kann dabei mitlesen und das echte Passwort wird nicht ständig hin und her transferiert.
Tokens kannst Du im zweiten Tab Auth
unter der URL hinzufügen. Häufig findest Du den Bearer Toke
n vor. Dieser ist ein langer String von zufälligen Zeichen.
Cookies Cache nutzen
Andere API setzen einen Cookie, welchen Du unter dem Tab Cookies wiederfindest.
Diese Authentifizierung-Form ist die sicherste Methode für moderne Single Page Applications (Anwendung von Angular bis Ionic). Der Cookie ist eine kleine Datei, welcher der Client speichert und zur Authentifizierung wie ein Schlüssel verwendet wird.
Cookies fügst Du nicht Deinem Anfragen zu, sondern die API sendet den Cookie mit der Antwort mit. Insomnia schnallt ab, mit jeder weiteren Anfrage den Cookie oben darauf.
Einstellungen prüfen
Nicht immer läuft alles rund mit den Anfragen. In Entwicklungsumgebung brauchst Du keine Validierung von TLS-Zertifikaten:
Application > Settings > General > Request / Response
→ Entferne den Harken bei Validate Certificates
Andere Probleme kann die HTTP-Version verursachen.
Alte / Dev-Server nutzen in der Regel HTTP 1.2 und HTTP 2 gehört zu den neueren Standards, welche eine deutliche Geschwindigkeitsoptimierung mit sich bringen. Insomnia unterstützt HTTP/3
noch nicht, aber Du solltest Dich als Entwickler mit der neuen Technologie frühzeitig befassen.
Weitere Probleme sind möglich, wenn Du in einem Unternehmensnetzwerk arbeitest. Für Entwickler wie Dich gibt es normalerweise Proxies, mit denen Du ungestört ins Internet herausspingen kannst. Manche Firewalls erachten den Entwickler Datenverkehr als schädlich und blockieren viele Anfragen. Gebe die Verbindungsdaten zum Proxy unter
Application > Settings > General > HTTP Network Proxy
an.
Alternative Postman
Du magst die Oberfläche von Insomnia nicht, dann verwende doch Postman. Postman ist ein weiteres API-Test-Tool, welches einen ähnlichen Funktionsumfang bietet. Wenn alle in Deinem Team Postman nutzen, solltest Du diesen auch nutzen. Nur soll, kannst Du Probleme genau nachzuvollziehen. Ein Tool Wirrwarr ist nicht die beste Basis für eine gute Zusammenarbeit.