Insomnia — co to jest, klient REST i GraphQL w programowaniu

Co to jest Insomnia i kluczowe funkcje

Insomnia — wieloplatformowa aplikacja (Electron) do wysyłania zapytań HTTP i debugowania API. Rozwijana przez firmę Kong od 2016 roku jako alternatywa dla Postman z naciskiem na szybkość działania i prywatność: dane są przechowywane lokalnie, synchronizacja w chmurze jest opcjonalna i wymaga rejestracji.

Interfejs i nawigacja

Główne okno jest podzielone na trzy kolumny: po lewej — drzewo zapytań (Workspace), pośrodku — edytor zapytań z zakładkami Params, Headers, Body, po prawej — panel odpowiedzi z trybami Pretty, Raw i Preview. Tryb ciemny jest włączony domyślnie, obsługiwane są własne motywy przez zmienne CSS.

Generowanie kodu

Insomnia obsługuje eksport zapytania do kodu w ponad 20 językach i frameworkach: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP i innych. Generator uwzględnia nagłówki, treść zapytania i typ uwierzytelniania, co przyspiesza integrację API z kodem aplikacji.

Insomnia vs Postman: porównanie klientów API

Insomnia i Postman rozwiązują to samo zadanie, ale z różnymi priorytetami. Insomnia jest lżejszy (~80 MB wobec ~300 MB), szybciej się uruchamia i działa w pełni offline bez narzucania rejestracji. Postman oferuje bardziej dojrzały ekosystem z monitorowaniem, serwerami mock i zespołowymi workspace.

Wybór narzędzia do zadania

Do indywidualnego programowania i szybkiego testowania endpointów Insomnia jest wygodniejszy dzięki lekkości i brakowi rejestracji. Do pracy zespołowej ze wspólną kolekcją, integracją CI/CD i monitorowaniem API produkcyjnego Postman pozostaje standardem branży.

Organizacja przestrzeni roboczej i środowisk

Workspace w Insomnia zawiera drzewo zapytań podzielone na foldery. Każde zapytanie może być typu HTTP, GraphQL, WebSocket lub gRPC. Obsługiwane jest przeciąganie, duplikowanie i grupowanie zapytań według kolorowych etykiet. Plik konfiguracyjny workspace jest przechowywany w formacie JSON.

Zmienne środowiskowe z dziedziczeniem

Insomnia obsługuje zagnieżdżone środowiska (Sub Environments), które dziedziczą zmienne rodzica. Pozwala to zdefiniować bazowy URL w środowisku globalnym i nadpisywać tylko różniące się parametry dla różnych środowisk. Zmienne są podstawiane przez składnię {`{`}_variable${`}`}.

// Przykład struktury środowiska Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Praca z GraphQL w Insomnia

Insomnia zapewnia jeden z najlepszych wśród klientów API edytorów GraphQL. Zakładka GraphQL Query pozwala pisać zapytania z autouzupełnianiem pól na podstawie załadowanego schematu. Po prawej stronie wyświetlana jest dokumentacja typów, pól i argumentów w czasie rzeczywistym.

Ładowanie schematu i Introspection

Schemat jest ładowany przez zapytanie GraphQL Introspection do endpointu. Insomnia buforuje schemat lokalnie i automatycznie aktualizuje go przy zmianach. Po załadowaniu dostępne są autouzupełnianie (Ctrl+Space), walidacja zapytania i podgląd możliwych błędów przed wysłaniem.

# Zapytanie GraphQL ze zmiennymi w Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Wtyczki i rozszerzanie możliwości

Insomnia Plugin Hub zawiera ponad 100 wtyczek rozszerzających funkcjonalność klienta. Wtyczki są instalowane przez menu Preferences → Plugins lub ręcznie przez npm. Popularne kategorie obejmują generowanie danych testowych, eksport do różnych formatów i niestandardowe walidatory odpowiedzi. Każda wtyczka przechodzi obowiązkową moderację przed publikacją we wspólnym hubie programistów.

Popularne wtyczki

• insomnia-plugin-faker — generowanie fałszywych danych (imię, email, telefon) do zapytań testowych.
• insomnia-plugin-aws4 — podpisywanie zapytań według AWS Signature Version 4 do pracy z Amazon API Gateway i S3.
• insomnia-plugin-utils — narzędzia do pracy z datami, hashowaniem i kodowaniem Base64 bezpośrednio w zapytaniach.

Wtyczki są pisane w JavaScript i współdziałają z Insomnia przez API szablonów (response.*, request.*, environment.*). Rozwój wtyczki wymaga podstawowej znajomości Node.js i publikacji przez pakiet npm z tagiem insomnia-plugin.

CLI i automatyzacja testowania

Inso CLI — narzędzie konsolowe wbudowane w Insomnia do uruchamiania zapytań i testów z terminala. Inso uruchamia pojedyncze zapytania lub całe kolekcje, eksportuje wyniki do JSON i może być zintegrowane z potokami CI/CD. Polecenie inso run collection sekwencyjnie wykonuje wszystkie zapytania w kolekcji.

Przykład integracji z GitHub Actions

Inso CLI działa w kontenerach Docker i trybie headless, co pozwala używać go w GitHub Actions i GitLab CI. Konfiguracja uruchamiania jest opisana w pliku YAML z podaniem ścieżki do wyeksportowanej kolekcji i środowiska. Obsługiwane są asercje na kod statusu i treść odpowiedzi przez skrypty JavaScript.

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

Integracja Insomnia z Git i praca zespołowa

Insomnia obsługuje synchronizację kolekcji przez Git. Pliki kolekcji są przechowywane w formacie JSON i mogą być dodane do repozytorium projektu. Insomnia zapewnia wbudowany klient Git do przeglądania zmian, tworzenia commitów i rozwiązywania konfliktów scalania bezpośrednio z interfejsu.

Konfiguracja synchronizacji Git

Aby podłączyć Git, utwórz lokalny folder z repozytorium i wskaż go jako katalog główny w ustawieniach Insomnia. Aplikacja automatycznie śledzi zmiany w plikach kolekcji i wyświetla je w panelu Version Control. Obsługiwane są standardowe operacje: commit, push, pull i podgląd diff między wersjami.

Praca zespołowa przez Insomnia Cloud

Dla projektów bez Git Insomnia oferuje synchronizację w chmurze przez Insomnia Cloud. Darmowy plan obejmuje do 3 członków zespołu i automatyczne tworzenie kopii zapasowych kolekcji. Plany płatne dodają zarządzanie dostępem, audyt zmian i priorytetowe wsparcie.

Design Mode i generowanie specyfikacji

Design Mode w Insomnia pozwala tworzyć specyfikacje API w formacie OpenAPI 3.0. Tryb działa jak edytor wizualny: definiuj endpointy i schematy danych bez ręcznego pisania YAML. Specyfikację można wyeksportować do JSON lub YAML.

Generowanie kolekcji z OpenAPI

Insomnia importuje specyfikacje OpenAPI i tworzy kolekcję zapytań dla każdego endpointu. Ścieżki i schematy są przekształcane w gotowe zapytania HTTP. Funkcja jest przydatna przy integracji z mikrousługami, gdzie specyfikacja jest przechowywana w osobnym repozytorium zespołu.

Tagowanie zapytań

Każdemu zapytaniu można przypisać kolorową etykietę: red, blue, green, orange, purple. Filtrowanie po tagach działa przez pole wyszukiwania niezależnie od struktury folderów, co ułatwia nawigację w projektach z setkami endpointów i wieloma modułami.

Design Mode i generowanie specyfikacji

Design Mode w Insomnia pozwala tworzyć specyfikacje API w formacie OpenAPI 3.0 bezpośrednio wewnątrz aplikacji. Tryb działa jak edytor wizualny: definiuj endpointy, schematy danych i parametry bez ręcznego pisania YAML. Specyfikację można wyeksportować do JSON lub YAML do publikacji w repozytorium.

Generowanie kolekcji z OpenAPI

Insomnia importuje istniejące specyfikacje OpenAPI i automatycznie tworzy kolekcję zapytań dla każdego endpointu. Ścieżki i schematy są przekształcane w gotowe zapytania HTTP z poprawnymi typami danych. Funkcja jest przydatna przy integracji z mikrousługami, gdzie specyfikacja jest przechowywana i utrzymywana przez osobny zespół programistów backendu.

Tagowanie i filtrowanie zapytań

Do organizacji dużej liczby zapytań Insomnia obsługuje tagowanie — każdemu zapytaniu można przypisać kolorową etykietę: red, blue, green, orange, purple. Filtrowanie po tagach działa przez pole wyszukiwania niezależnie od struktury folderów, co ułatwia nawigację w projektach z setkami endpointów i wieloma modułami funkcjonalnymi API.