Insomnia — ce este, client REST și GraphQL în dezvoltare

Ce este Insomnia și caracteristicile-cheie

Insomnia — aplicație multiplatformă (Electron) pentru trimiterea cererilor HTTP și depanarea API. Dezvoltată de compania Kong din 2016 ca alternativă la Postman, cu accent pe viteza de lucru și confidențialitate: datele sunt stocate local, sincronizarea în cloud este opțională și necesită înregistrare.

Interfață și navigare

Fereastra principală este împărțită în trei coloane: în stânga — arborele cererilor (Workspace), în centru — editorul de cereri cu filele Params, Headers, Body, în dreapta — panoul de răspuns cu modurile Pretty, Raw și Preview. Tema întunecată este activată implicit, fiind acceptate teme personalizate prin variabile CSS.

Generarea codului

Insomnia acceptă exportul cererii în cod în peste 20 de limbaje și frameworkuri: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP și altele. Generatorul ia în considerare antetele, corpul cererii și tipul de autentificare, ceea ce accelerează integrarea API în codul aplicației.

Insomnia vs Postman: compararea clienților API

Insomnia și Postman rezolvă aceeași sarcină, dar cu priorități diferite. Insomnia este mai ușor (~80 MB față de ~300 MB), se pornește mai repede și funcționează complet offline fără a impune înregistrarea. Postman oferă un ecosistem mai matur, cu monitorizare, servere mock și workspace-uri de echipă.

Alegerea instrumentului pentru sarcină

Pentru dezvoltarea individuală și testarea rapidă a endpointurilor, Insomnia este mai comod datorită ușurinței și lipsei înregistrării. Pentru munca de echipă cu o colecție comună, integrare CI/CD și monitorizarea API-ului de producție, Postman rămâne standardul industriei.

Organizarea spațiului de lucru și a mediilor

Workspace în Insomnia conține arborele cererilor, împărțit în foldere. Fiecare cerere poate fi de tip HTTP, GraphQL, WebSocket sau gRPC. Sunt acceptate glisarea, duplicarea și gruparea cererilor după etichete colorate. Fișierul de configurare al workspace-ului este stocat în format JSON.

Variabile de mediu cu moștenire

Insomnia acceptă medii imbricate (Sub Environments), care moștenesc variabilele părinte. Aceasta permite definirea URL-ului de bază în mediul global și suprascrierea doar a parametrilor diferiți pentru diferite medii. Variabilele sunt înlocuite prin sintaxa {`{`}_variable${`}`}.

// Exemplu de structură a mediului Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Lucrul cu GraphQL în Insomnia

Insomnia oferă unul dintre cele mai bune editoare GraphQL dintre clienții API. Fila GraphQL Query permite scrierea cererilor cu completare automată a câmpurilor pe baza schemei încărcate. În dreapta este afișată documentația tipurilor, câmpurilor și argumentelor în timp real.

Încărcarea schemei și Introspection

Schema este încărcată printr-o cerere GraphQL Introspection către endpoint. Insomnia păstrează schema în cache local și o actualizează automat la modificări. După încărcare devin disponibile completarea automată (Ctrl+Space), validarea cererii și previzualizarea erorilor posibile înainte de trimitere.

# Cerere GraphQL cu variabile în Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Pluginuri și extinderea posibilităților

Insomnia Plugin Hub conține peste 100 de pluginuri care extind funcționalitatea clientului. Pluginurile se instalează prin meniul Preferences → Plugins sau manual prin npm. Categoriile populare includ generarea datelor de test, exportul în diferite formate și validatori personalizați de răspuns. Fiecare plugin trece prin moderare obligatorie înainte de publicare în hub-ul comun al dezvoltatorilor.

Pluginuri populare

• insomnia-plugin-faker — generarea de date false (nume, email, telefon) pentru cererile de test.
• insomnia-plugin-aws4 — semnarea cererilor după AWS Signature Version 4 pentru lucrul cu Amazon API Gateway și S3.
• insomnia-plugin-utils — utilitare pentru lucrul cu date, hashing și codificare Base64 direct în cereri.

Pluginurile sunt scrise în JavaScript și interacționează cu Insomnia prin API-ul de templateuri (response.*, request.*, environment.*). Dezvoltarea unui plugin necesită cunoștințe de bază de Node.js și publicarea printr-un pachet npm cu eticheta insomnia-plugin.

CLI și automatizarea testării

Inso CLI — utilitar de consolă integrat în Insomnia pentru rularea cererilor și testelor din terminal. Inso rulează cereri individuale sau colecții întregi, exportă rezultatele în JSON și poate fi integrat în pipeline-uri CI/CD. Comanda inso run collection execută secvențial toate cererile din colecție.

Exemplu de integrare în GitHub Actions

Inso CLI funcționează în containere Docker și mod headless, ceea ce permite utilizarea sa în GitHub Actions și GitLab CI. Configurația de rulare este descrisă într-un fișier YAML cu indicarea căii către colecția exportată și mediu. Sunt acceptate aserțiuni asupra codului de stare și corpului răspunsului prin scripturi JavaScript.

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

Integrarea Insomnia cu Git și lucrul în echipă

Insomnia acceptă sincronizarea colecțiilor prin Git. Fișierele colecțiilor sunt stocate în format JSON și pot fi adăugate în repository-ul proiectului. Insomnia oferă un client Git integrat pentru vizualizarea modificărilor, crearea de commit-uri și rezolvarea conflictelor de fuzionare direct din interfață.

Configurarea sincronizării Git

Pentru a conecta Git, creați un folder local cu repository și indicați-l ca director rădăcină în setările Insomnia. Aplicația urmărește automat modificările din fișierele colecției și le afișează în panoul Version Control. Sunt acceptate operații standard: commit, push, pull și vizualizarea diff între versiuni.

Lucrul în echipă prin Insomnia Cloud

Pentru proiectele fără Git, Insomnia oferă sincronizare în cloud prin Insomnia Cloud. Tariful gratuit include până la 3 membri ai echipei și copierea automată de rezervă a colecțiilor. Tarifele plătite adaugă gestionarea accesului, auditul modificărilor și suport prioritar.

Design Mode și generarea specificațiilor

Design Mode în Insomnia permite crearea specificațiilor API în format OpenAPI 3.0. Modul funcționează ca un editor vizual: definiți endpointuri și scheme de date fără a scrie YAML manual. Specificația poate fi exportată în JSON sau YAML.

Generarea colecției din OpenAPI

Insomnia importă specificații OpenAPI și creează o colecție de cereri pentru fiecare endpoint. Căile și schemele sunt transformate în cereri HTTP gata făcute. Funcția este utilă la integrarea cu microserviciile, unde specificația este stocată într-un repository separat al echipei.

Etichetarea cererilor

Fiecărei cereri i se poate atribui o etichetă colorată: red, blue, green, orange, purple. Filtrarea după etichete funcționează prin bara de căutare independent de structura folderelor, ceea ce simplifică navigarea în proiecte cu sute de endpointuri și multe module.

Design Mode și generarea specificațiilor

Design Mode în Insomnia permite crearea specificațiilor API în format OpenAPI 3.0 direct în interiorul aplicației. Modul funcționează ca un editor vizual: definiți endpointuri, scheme de date și parametri fără a scrie YAML manual. Specificația poate fi exportată în JSON sau YAML pentru publicare în repository.

Generarea colecției din OpenAPI

Insomnia importă specificații OpenAPI existente și creează automat o colecție de cereri pentru fiecare endpoint. Căile și schemele sunt transformate în cereri HTTP gata făcute cu tipuri de date corecte. Această funcție este utilă la integrarea cu microserviciile, unde specificația este stocată și întreținută de o echipă separată de dezvoltatori backend.

Etichetarea și filtrarea cererilor

Pentru organizarea unui număr mare de cereri, Insomnia acceptă etichetarea — fiecărei cereri i se poate atribui o etichetă colorată: red, blue, green, orange, purple. Filtrarea după etichete funcționează prin bara de căutare independent de structura folderelor, ceea ce simplifică navigarea în proiecte cu sute de endpointuri și multe module funcționale de API.