Insomnia — co to je, klient REST a GraphQL ve vývoji

Co je Insomnia a klíčové vlastnosti

Insomnia — multiplatformní aplikace (Electron) pro odesílání HTTP požadavků a ladění API. Od roku 2016 ji vyvíjí společnost Kong jako alternativu k Postmanu s důrazem na rychlost práce a soukromí: data se ukládají lokálně, cloudová synchronizace je volitelná a vyžaduje registraci.

Rozhraní a navigace

Hlavní okno je rozděleno na tři sloupce: vlevo — strom požadavků (Workspace), uprostřed — editor požadavků s kartami Params, Headers, Body, vpravo — panel odpovědi s režimy Pretty, Raw a Preview. Temné téma je ve výchozím nastavení zapnuto, vlastní témata jsou podporována přes CSS proměnné.

Generování kódu

Insomnia podporuje export požadavku do kódu ve více než 20 jazycích a frameworky: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP a další. Generátor zohledňuje hlavičky, tělo požadavku a typ autentizace, což urychluje integraci API do kódu aplikace.

Insomnia vs Postman: srovnání API klientů

Insomnia a Postman řeší stejný úkol, ale s různými prioritami. Insomnia je lehčí (~80 MB oproti ~300 MB), rychleji se spouští a funguje zcela offline, aniž by vnucoval registraci. Postman nabízí vyspělejší ekosystém s monitorováním, mock servery a týmovými workspace.

Výběr nástroje podle úkolu

Pro individuální vývoj a rychlé testování endpointů je Insomnia pohodlnější díky své lehkosti a absenci registrace. Pro týmovou práci se společnou kolekcí, integrací CI/CD a monitorováním produkčního API zůstává Postman průmyslovým standardem.

Organizace pracovního prostoru a prostředí

Workspace v Insomnia obsahuje strom požadavků rozdělený do složek. Každý požadavek může být typu HTTP, GraphQL, WebSocket nebo gRPC. Je podporováno přetahování, duplikování a seskupování požadavků podle barevných štítků. Konfigurační soubor workspace se ukládá ve formátu JSON.

Proměnné prostředí s děděním

Insomnia podporuje vnořená prostředí (Sub Environments), která dědí proměnné rodiče. To umožňuje definovat základní URL v globálním prostředí a přepisovat pouze rozdílné parametry pro různá prostředí. Proměnné se dosazují syntaxí {`{`}_variable${`}`}.

// Příklad struktury prostředí Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Práce s GraphQL v Insomnia

Insomnia nabízí jeden z nejlepších editorů GraphQL mezi API klienty. Karta GraphQL Query umožňuje psát požadavky s automatickým doplňováním polí na základě načteného schématu. Vpravo se v reálném čase zobrazuje dokumentace typů, polí a argumentů.

Načítání schématu a Introspection

Schéma se načítá pomocí požadavku GraphQL Introspection na endpoint. Insomnia ukládá schéma do lokální mezipaměti a automaticky ho aktualizuje při změnách. Po načtení jsou dostupné automatické doplňování (Ctrl+Space), validace požadavku a náhled možných chyb před odesláním.

# GraphQL požadavek s proměnnými v Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Pluginy a rozšíření možností

Insomnia Plugin Hub obsahuje více než 100 pluginů rozšiřujících funkčnost klienta. Pluginy se instalují přes nabídku Preferences → Plugins nebo ručně přes npm. Populární kategorie zahrnují generování testovacích dat, export do různých formátů a vlastní validátory odpovědí. Každý plugin prochází povinnou moderací před publikováním ve společném hubu vývojářů.

Populární pluginy

• insomnia-plugin-faker — generování falešných dat (jméno, e-mail, telefon) pro testovací požadavky.
• insomnia-plugin-aws4 — podepisování požadavků podle AWS Signature Version 4 pro práci s Amazon API Gateway a S3.
• insomnia-plugin-utils — nástroje pro práci s daty, hashování a kódování Base64 přímo v požadavcích.

Pluginy se píší v JavaScriptu a komunikují s Insomnia přes API pro šablony (response.*, request.*, environment.*). Vývoj pluginu vyžaduje základní znalost Node.js a publikování prostřednictvím balíčku npm s tagem insomnia-plugin.

CLI a automatizace testování

Inso CLI — konzolový nástroj zabudovaný v Insomnia pro spouštění požadavků a testů z terminálu. Inso spouští jednotlivé požadavky nebo celé kolekce, exportuje výsledky do JSON a lze ho integrovat do pipeline CI/CD. Příkaz inso run collection postupně provede všechny požadavky v kolekci.

Příklad integrace do GitHub Actions

Inso CLI funguje v kontejnerech Docker a v headless režimu, což umožňuje jeho použití v GitHub Actions a GitLab CI. Konfigurace spuštění je popsána v souboru YAML s uvedením cesty k exportované kolekci a prostředí. Jsou podporovány aserce na stavový kód a tělo odpovědi prostřednictvím JavaScript skriptů.

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

Integrace Insomnia s Gitem a týmová práce

Insomnia podporuje synchronizaci kolekcí přes Git. Soubory kolekcí se ukládají ve formátu JSON a lze je přidat do repozitáře projektu. Insomnia poskytuje vestavěného Git klienta pro prohlížení změn, vytváření commitů a řešení konfliktů při sloučení přímo z rozhraní.

Nastavení synchronizace Git

Pro připojení Gitu vytvořte lokální složku s repozitářem a označte ji jako kořenový adresář v nastavení Insomnia. Aplikace automaticky sleduje změny v souborech kolekce a zobrazuje je v panelu Version Control. Jsou podporovány standardní operace: commit, push, pull a prohlížení diff mezi verzemi.

Týmová práce přes Insomnia Cloud

Pro projekty bez Gitu nabízí Insomnia cloudovou synchronizaci prostřednictvím Insomnia Cloud. Bezplatný tarif zahrnuje až 3 členy týmu a automatické zálohování kolekcí. Placené tarify přidávají správu přístupu, audit změn a prioritní podporu.

Design Mode a generování specifikací

Design Mode v Insomnia umožňuje vytvářet API specifikace ve formátu OpenAPI 3.0. Režim funguje jako vizuální editor: definujte endpointy a schémata dat bez ručního psaní YAML. Specifikaci lze exportovat do JSON nebo YAML.

Generování kolekce z OpenAPI

Insomnia importuje specifikace OpenAPI a vytváří kolekci požadavků pro každý endpoint. Cesty a schémata se převádějí na hotové HTTP požadavky. Funkce je užitečná při integraci s mikroslužbami, kde je specifikace uložena v samostatném repozitáři týmu.

Tagování požadavků

Každému požadavku lze přiřadit barevný štítek: red, blue, green, orange, purple. Filtrování podle tagů funguje přes vyhledávací pole nezávisle na struktuře složek, což zjednodušuje navigaci v projektech se stovkami endpointů a mnoha moduly.

Design Mode a generování specifikací

Design Mode v Insomnia umožňuje vytvářet API specifikace ve formátu OpenAPI 3.0 přímo uvnitř aplikace. Režim funguje jako vizuální editor: definujte endpointy, schémata dat a parametry bez ručního psaní YAML. Specifikaci lze exportovat do JSON nebo YAML pro publikování v repozitáři.

Generování kolekce z OpenAPI

Insomnia importuje existující specifikace OpenAPI a automaticky vytváří kolekci požadavků pro každý endpoint. Cesty a schémata se převádějí na hotové HTTP požadavky se správnými datovými typy. Tato funkce je užitečná při integraci s mikroslužbami, kde specifikaci ukládá a udržuje samostatný tým backend vývojářů.

Tagování a filtrování požadavků

Pro organizaci velkého počtu požadavků podporuje Insomnia tagování — každému požadavku lze přiřadit barevný štítek: red, blue, green, orange, purple. Filtrování podle tagů funguje přes vyhledávací pole nezávisle na struktuře složek, což zjednodušuje navigaci v projektech se stovkami endpointů a mnoha funkčními API moduly.