Insomnia — was ist das, REST- und GraphQL-Client in der Entwicklung

Was ist Insomnia und die wichtigsten Funktionen

Insomnia ist eine plattformübergreifende Anwendung (Electron) zum Senden von HTTP-Anfragen und zum Debuggen von APIs. Sie wird seit 2016 von der Firma Kong als Alternative zu Postman entwickelt, mit Fokus auf Geschwindigkeit und Datenschutz: Die Daten werden lokal gespeichert, die Cloud-Synchronisation ist optional und erfordert eine Registrierung.

Oberfläche und Navigation

Das Hauptfenster ist in drei Spalten unterteilt: links der Anfragebaum (Workspace), in der Mitte der Anfrage-Editor mit den Tabs Params, Headers, Body, rechts das Antwortpanel mit den Modi Pretty, Raw und Preview. Das dunkle Thema ist standardmäßig aktiviert, benutzerdefinierte Themen werden über CSS-Variablen unterstützt.

Codegenerierung

Insomnia unterstützt den Export einer Anfrage in Code in über 20 Sprachen und Frameworks: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP und andere. Der Generator berücksichtigt Header, den Anfragebody und den Authentifizierungstyp, was die API-Integration in den Anwendungscode beschleunigt.

Insomnia vs. Postman: Vergleich der API-Clients

Insomnia und Postman lösen dieselbe Aufgabe, aber mit unterschiedlichen Prioritäten. Insomnia ist leichter (~80 MB gegenüber ~300 MB), startet schneller und arbeitet vollständig offline, ohne eine Registrierung aufzuzwingen. Postman bietet ein ausgereifteres Ökosystem mit Monitoring, Mock-Servern und Team-Workspaces.

Auswahl des Werkzeugs für die Aufgabe

Für die individuelle Entwicklung und das schnelle Testen von Endpunkten ist Insomnia dank seiner Leichtigkeit und der fehlenden Registrierung bequemer. Für Teamarbeit mit einer gemeinsamen Sammlung, CI/CD-Integration und Monitoring von Produktions-APIs bleibt Postman der Industriestandard.

Organisation des Arbeitsbereichs und der Umgebungen

Der Workspace in Insomnia enthält einen Anfragebaum, der in Ordner unterteilt ist. Jede Anfrage kann vom Typ HTTP, GraphQL, WebSocket oder gRPC sein. Drag-and-Drop, Duplizieren und Gruppieren von Anfragen nach Farblabels werden unterstützt. Die Konfigurationsdatei des Workspace wird im JSON-Format gespeichert.

Umgebungsvariablen mit Vererbung

Insomnia unterstützt verschachtelte Umgebungen (Sub Environments), die die Variablen des übergeordneten Elements erben. Dadurch kann eine Basis-URL in der globalen Umgebung definiert und für verschiedene Umgebungen nur die abweichenden Parameter überschrieben werden. Variablen werden über die Syntax {`{`}_variable${`}`} eingesetzt.

// Beispiel für die Struktur einer Insomnia-Umgebung
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Arbeiten mit GraphQL in Insomnia

Insomnia bietet einen der besten GraphQL-Editoren unter den API-Clients. Über den Tab GraphQL Query lassen sich Anfragen mit Feld-Autovervollständigung auf Basis des geladenen Schemas schreiben. Rechts wird die Dokumentation zu Typen, Feldern und Argumenten in Echtzeit angezeigt.

Laden des Schemas und Introspection

Das Schema wird über eine GraphQL-Introspection-Anfrage an den Endpunkt geladen. Insomnia speichert das Schema lokal im Cache und aktualisiert es bei Änderungen automatisch. Nach dem Laden stehen die Autovervollständigung (Ctrl+Space), die Validierung der Anfrage und die Vorschau möglicher Fehler vor dem Senden zur Verfügung.

# GraphQL-Abfrage mit Variablen in Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Plugins und Erweiterung der Funktionen

Insomnia Plugin Hub enthält mehr als 100 Plugins, die die Funktionalität des Clients erweitern. Plugins werden über das Menü Preferences → Plugins oder manuell über npm installiert. Zu den beliebten Kategorien gehören die Generierung von Testdaten, der Export in verschiedene Formate und benutzerdefinierte Antwortvalidatoren. Jedes Plugin durchläuft vor der Veröffentlichung im öffentlichen Entwickler-Hub eine obligatorische Moderation.

Beliebte Plugins

• insomnia-plugin-faker — Generierung von Fake-Daten (Name, E-Mail, Telefon) für Testanfragen.
• insomnia-plugin-aws4 — Signierung von Anfragen mit AWS Signature Version 4 für die Arbeit mit Amazon API Gateway und S3.
• insomnia-plugin-utils — Dienstprogramme für die Arbeit mit Datumsangaben, Hashing und Base64-Kodierung direkt in Anfragen.

Plugins werden in JavaScript geschrieben und interagieren über die Template-API (response.*, request.*, environment.*) mit Insomnia. Die Entwicklung eines Plugins erfordert Grundkenntnisse in Node.js und die Veröffentlichung über ein npm-Paket mit dem Tag insomnia-plugin.

CLI und Testautomatisierung

Inso CLI ist ein in Insomnia integriertes Konsolendienstprogramm zum Ausführen von Anfragen und Tests aus dem Terminal. Inso führt einzelne Anfragen oder ganze Sammlungen aus, exportiert Ergebnisse nach JSON und kann in CI/CD-Pipelines integriert werden. Der Befehl inso run collection führt alle Anfragen einer Sammlung nacheinander aus.

Beispiel für die Integration in GitHub Actions

Inso CLI arbeitet in Docker-Containern und im Headless-Modus, sodass es in GitHub Actions und GitLab CI eingesetzt werden kann. Die Startkonfiguration wird in einer YAML-Datei mit dem Pfad zur exportierten Sammlung und zur Umgebung beschrieben. Assertions auf Statuscode und Antwortbody werden über JavaScript-Skripte unterstützt.

# GitHub Actions Workflow mit Inso CLI
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

Integration von Insomnia mit Git und Teamarbeit

Insomnia unterstützt die Synchronisation von Sammlungen über Git. Sammlungsdateien werden im JSON-Format gespeichert und können zum Projektrepository hinzugefügt werden. Insomnia bietet einen integrierten Git-Client zum Anzeigen von Änderungen, Erstellen von Commits und Lösen von Merge-Konflikten direkt aus der Oberfläche.

Einrichtung der Git-Synchronisation

Um Git zu verbinden, erstellen Sie einen lokalen Ordner mit einem Repository und legen ihn in den Insomnia-Einstellungen als Stammverzeichnis fest. Die Anwendung verfolgt Änderungen in Sammlungsdateien automatisch und zeigt sie im Panel Version Control an. Standardoperationen werden unterstützt: commit, push, pull und Diff-Anzeige zwischen Versionen.

Teamarbeit über Insomnia Cloud

Für Projekte ohne Git bietet Insomnia Cloud-Synchronisation über Insomnia Cloud an. Der kostenlose Tarif umfasst bis zu 3 Teammitglieder und automatische Sicherung von Sammlungen. Bezahlte Tarife fügen Zugriffsverwaltung, Änderungsprüfung und Prioritäts-Support hinzu.

Design Mode und Generierung von Spezifikationen

Design Mode in Insomnia ermöglicht es, API-Spezifikationen im OpenAPI-3.0-Format zu erstellen. Der Modus funktioniert wie ein visueller Editor: Definieren Sie Endpunkte und Datenschemata, ohne YAML von Hand zu schreiben. Die Spezifikation kann nach JSON oder YAML exportiert werden.

Generierung einer Sammlung aus OpenAPI

Insomnia importiert OpenAPI-Spezifikationen und erstellt für jeden Endpunkt eine Sammlung von Anfragen. Pfade und Schemata werden in fertige HTTP-Anfragen umgewandelt. Die Funktion ist bei der Integration mit Microservices nützlich, bei der die Spezifikation in einem separaten Team-Repository gespeichert wird.

Tagging von Anfragen

Jeder Anfrage kann ein farbiges Label zugewiesen werden: red, blue, green, orange, purple. Die Filterung nach Tags funktioniert über die Suchleiste unabhängig von der Ordnerstruktur, was die Navigation in Projekten mit Hunderten von Endpunkten und vielen Modulen vereinfacht.

Design Mode und Generierung von Spezifikationen

Design Mode in Insomnia ermöglicht es, API-Spezifikationen im OpenAPI-3.0-Format direkt in der Anwendung zu erstellen. Der Modus funktioniert wie ein visueller Editor: Definieren Sie Endpunkte, Datenschemata und Parameter, ohne YAML von Hand zu schreiben. Die Spezifikation kann zur Veröffentlichung in Repositories nach JSON oder YAML exportiert werden.

Generierung einer Sammlung aus OpenAPI

Insomnia importiert vorhandene OpenAPI-Spezifikationen und erstellt automatisch für jeden Endpunkt eine Sammlung von Anfragen. Pfade und Schemata werden in fertige HTTP-Anfragen mit korrekten Datentypen umgewandelt. Diese Funktion ist bei der Integration mit Microservices nützlich, bei der die Spezifikation von einem separaten Backend-Entwicklungsteam gespeichert und gepflegt wird.

Tagging und Filterung von Anfragen

Zur Organisation einer großen Anzahl von Anfragen unterstützt Insomnia Tagging — jeder Anfrage kann ein farbiges Label zugewiesen werden: red, blue, green, orange, purple. Die Filterung nach Tags funktioniert über die Suchleiste unabhängig von der Ordnerstruktur, was die Navigation in Projekten mit Hunderten von Endpunkten und vielen funktionalen API-Modulen vereinfacht.