Insomnia — mi ez, REST és GraphQL kliens a fejlesztésben

Mi az Insomnia és a legfontosabb jellemzői

Insomnia — többplatformos alkalmazás (Electron) HTTP-kérések küldésére és API-k hibakeresésére. A Kong vállalat fejleszti 2016 óta a Postman alternatívájaként, a munka sebességére és a magánélet védelmére összpontosítva: az adatokat helyben tárolja, a felhőszinkronizáció opcionális és regisztrációt igényel.

Felület és navigáció

A főablak három oszlopra van osztva: balra — a kérések fája (Workspace), középen — a kérészerkesztő a Params, Headers, Body fülekkel, jobbra — a válaszpanel a Pretty, Raw és Preview módokkal. A sötét téma alapértelmezés szerint be van kapcsolva, az egyéni témák CSS-változókon keresztül támogatottak.

Kódgenerálás

Az Insomnia támogatja a kérés exportálását kódba több mint 20 nyelven és keretrendszerben: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP és mások. A generátor figyelembe veszi a fejléceket, a kérés törzsét és a hitelesítés típusát, ami felgyorsítja az API integrálását az alkalmazás kódjába.

Insomnia vs Postman: API-kliensek összehasonlítása

Insomnia és a Postman ugyanazt a feladatot oldja meg, de eltérő prioritásokkal. Az Insomnia könnyebb (~80 MB a ~300 MB-hoz képest), gyorsabban indul és teljesen offline működik anélkül, hogy regisztrációt erőltetne. A Postman érettebb ökoszisztémát kínál monitoringgal, mock-szerverekkel és csapatos workspace-ekkel.

Az eszköz kiválasztása a feladathoz

Az egyéni fejlesztéshez és az endpointok gyors teszteléséhez az Insomnia kényelmesebb a könnyűsége és a regisztráció hiánya miatt. A közös kollekcióval, CI/CD-integrációval és éles API-k monitoringjával járó csapatmunkához a Postman marad az iparági szabvány.

Munkaterület és környezetek szervezése

Workspace az Insomnia-ban tartalmazza a kérések fáját, mappákra bontva. Minden kérés lehet HTTP, GraphQL, WebSocket vagy gRPC típusú. Támogatott a húzás, a másolás és a kérések csoportosítása színes címkék szerint. A workspace konfigurációs fájlja JSON formátumban van tárolva.

Környezeti változók örökléssel

Az Insomnia támogatja a beágyazott környezeteket (Sub Environments), amelyek öröklik a szülő változóit. Ez lehetővé teszi az alap URL meghatározását a globális környezetben, és csak a különböző paraméterek felülírását a különböző környezetekhez. A változók a {`{`}_variable${`}`} szintaxissal helyettesítődnek.

// Példa az Insomnia-környezet szerkezetére
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

GraphQL-használat az Insomnia-ban

Insomnia az egyik legjobb GraphQL-szerkesztőt kínálja az API-kliensek között. A GraphQL Query fül lehetővé teszi kérések írását a mezők automatikus kiegészítésével a betöltött séma alapján. A jobb oldalon valós időben jelenik meg a típusok, mezők és argumentumok dokumentációja.

Séma betöltése és Introspection

A séma GraphQL Introspection kéréssel töltődik be az endpointra. Az Insomnia helyben cache-eli a sémát, és változások esetén automatikusan frissíti. A betöltés után elérhetővé válik az automatikus kiegészítés (Ctrl+Space), a kérés érvényesítése és a lehetséges hibák előnézete a küldés előtt.

# GraphQL-kérés változókkal az Insomnia-ban
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Pluginok és lehetőségek bővítése

Insomnia Plugin Hub több mint 100 plugint tartalmaz, amelyek bővítik a kliens funkcionalitását. A pluginok a Preferences → Plugins menün vagy manuálisan, npm-en keresztül telepíthetők. A népszerű kategóriák közé tartozik a tesztadatok generálása, az exportálás különböző formátumokba és az egyéni válasz-validátorok. Minden plugin kötelező moderáláson esik át, mielőtt megjelenik a fejlesztők közös hub-jában.

Népszerű pluginok

• insomnia-plugin-faker — hamis adatok (név, e-mail, telefon) generálása tesztkérésekhez.
• insomnia-plugin-aws4 — kérések aláírása AWS Signature Version 4 szerint az Amazon API Gateway és az S3 használatához.
• insomnia-plugin-utils — segédprogramok dátumokkal, hasheléssel és Base64-kódolással való munkához közvetlenül a kérésekben.

A pluginok JavaScript nyelven íródnak, és a sablonozó API-n keresztül kommunikálnak az Insomnia-val (response.*, request.*, environment.*). A plugin fejlesztése a Node.js alapvető ismeretét és az insomnia-plugin címkével ellátott npm-csomagon keresztüli közzétételt igényel.

CLI és tesztelés automatizálása

Inso CLI — az Insomnia-ba beépített konzolos segédprogram kérések és tesztek futtatásához a terminálból. Az Inso egyes kéréseket vagy teljes kollekciókat futtat, JSON-ba exportálja az eredményeket, és CI/CD-folyamatokba integrálható. A inso run collection parancs egymás után hajtja végre a kollekció összes kérését.

Integráció a GitHub Actions-be — példa

Az Inso CLI Docker-konténerekben és headless módban működik, ami lehetővé teszi használatát a GitHub Actions-ben és a GitLab CI-ben. A futtatási konfigurációt YAML-fájl írja le az exportált kollekció és környezet elérési útjának megadásával. A státuszkódra és a válasz törzsére vonatkozó állítások JavaScript-szkripteken keresztül támogatottak.

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

Az Insomnia integrálása a Git-tel és csapatmunka

Insomnia támogatja a kollekciók szinkronizálását a Git-en keresztül. A kollekciófájlok JSON formátumban vannak tárolva, és hozzáadhatók a projekt adattárához. Az Insomnia beépített Git-klienst biztosít a változások megtekintéséhez, commitok létrehozásához és az egyesítési konfliktusok feloldásához közvetlenül a felületről.

A Git-szinkronizáció beállítása

A Git csatlakoztatásához hozzon létre egy helyi mappát adattárral, és jelölje meg gyökérkönyvtárként az Insomnia beállításaiban. Az alkalmazás automatikusan nyomon követi a kollekciófájlok változásait, és megjeleníti azokat a Version Control panelen. Támogatottak a szokásos műveletek: commit, push, pull és a verziók közötti diff megtekintése.

Csapatmunka az Insomnia Cloud-on keresztül

A Git nélküli projektekhez az Insomnia felhőszinkronizációt kínál az Insomnia Cloud-on keresztül. Az ingyenes tarifa legfeljebb 3 csapattagot és a kollekciók automatikus biztonsági mentését tartalmazza. A fizetős tarifák hozzáadják a hozzáférés-kezelést, a változások auditálását és az elsőbbségi támogatást.

Design Mode és specifikációk generálása

Design Mode az Insomnia-ban lehetővé teszi API-specifikációk létrehozását OpenAPI 3.0 formátumban. A mód vizuális szerkesztőként működik: definiáljon endpointokat és adatsémákat a YAML kézi írása nélkül. A specifikáció JSON-ba vagy YAML-ba exportálható.

Kollekció generálása OpenAPI-ból

Az Insomnia importálja az OpenAPI-specifikációkat, és minden endpointhoz kollekciót hoz létre kérésekből. Az útvonalak és sémák kész HTTP-kérésekké alakulnak. A funkció hasznos a mikroszolgáltatásokkal való integrációnál, ahol a specifikációt a csapat külön adattárában tárolják.

Kérések címkézése

Minden kéréshez hozzárendelhető színes címke: red, blue, green, orange, purple. A címkék szerinti szűrés a keresősávon keresztül működik, a mappastruktúrától függetlenül, ami megkönnyíti a navigációt a több száz endpointot és sok modult tartalmazó projektekben.

Design Mode és specifikációk generálása

Design Mode az Insomnia-ban lehetővé teszi API-specifikációk létrehozását OpenAPI 3.0 formátumban közvetlenül az alkalmazáson belül. A mód vizuális szerkesztőként működik: definiáljon endpointokat, adatsémákat és paramétereket a YAML kézi írása nélkül. A specifikáció közzétételhez JSON-ba vagy YAML-ba exportálható az adattárba.

Kollekció generálása OpenAPI-ból

Az Insomnia importálja a meglévő OpenAPI-specifikációkat, és automatikusan kérésekből álló kollekciót hoz létre minden endpointhoz. Az útvonalak és sémák kész HTTP-kérésekké alakulnak helyes adattípusokkal. Ez a funkció hasznos a mikroszolgáltatásokkal való integrációnál, ahol a specifikációt a backend-fejlesztők külön csapata tárolja és karbantartja.

Kérések címkézése és szűrése

A nagyszámú kérés rendszerezéséhez az Insomnia támogatja a címkézést — minden kéréshez hozzárendelhető színes címke: red, blue, green, orange, purple. A címkék szerinti szűrés a keresősávon keresztül működik, a mappastruktúrától függetlenül, ami megkönnyíti a navigációt a több száz endpointot és sok funkcionális API-modult tartalmazó projektekben.