Insomnia — какво е това, REST и GraphQL клиент в разработката

Какво е Insomnia и ключовите характеристики

Insomnia — крос-платформена приложение (Electron) за изпращане на HTTP заявки и отстраняване на грешки в API. Разработва се от компанията Kong от 2016 г. като алтернатива на Postman с акцент върху скоростта на работа и поверителността: данните се съхраняват локално, облачната синхронизация е по избор и изисква регистрация.

Интерфейс и навигация

Основният прозорец е разделен на три колони: отляво — дървото на заявките (Workspace), в средата — редакторът на заявки с разделите Params, Headers, Body, отдясно — панелът за отговор с режимите Pretty, Raw и Preview. Тъмната тема е включена по подразбиране, като се поддържат персонализирани теми чрез CSS променливи.

Генериране на код

Insomnia поддържа експорт на заявката в код на над 20 езика и рамки: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP и други. Генераторът отчита заглавията, тялото на заявката и вида на автентикацията, което ускорява интегрирането на API в кода на приложението.

Insomnia срещу Postman: сравнение на API клиенти

Insomnia и Postman решават една и съща задача, но с различни приоритети. Insomnia е по-лек (~80 MB срещу ~300 MB), стартира по-бързо и работи напълно офлайн, без да налага регистрация. Postman предлага по-зряла екосистема с мониторинг, mock сървъри и екипни работни пространства.

Избор на инструмент според задачата

За индивидуална разработка и бързо тестване на крайни точки Insomnia е по-удобен благодарение на лекотата си и липсата на регистрация. За екипна работа с обща колекция, CI/CD интеграция и мониторинг на производствен API Postman остава индустриален стандарт.

Организация на работното пространство и средите

Workspace в Insomnia съдържа дървото на заявките, разделено на папки. Всяка заявка може да бъде от тип HTTP, GraphQL, WebSocket или gRPC. Поддържат се влачене, дублиране и групиране на заявки по цветни етикети. Конфигурационният файл на работното пространство се съхранява във формат JSON.

Променливи на средата с наследяване

Insomnia поддържа вложени среди (Sub Environments), които наследяват променливите на родителя. Това позволява да се зададе основен URL в глобалната среда и да се презаписват само различаващите се параметри за различните среди. Променливите се заместват чрез синтаксиса {`{`}_variable${`}`}.

// Пример за структура на средата на Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Работа с GraphQL в Insomnia

Insomnia предоставя един от най-добрите редактори за GraphQL сред API клиентите. Разделът GraphQL Query позволява писане на заявки с автоматично довършване на полетата въз основа на заредената схема. Отдясно в реално време се показва документация за типовете, полетата и аргументите.

Зареждане на схемата и Introspection

Схемата се зарежда чрез GraphQL Introspection заявка към крайната точка. Insomnia кешира схемата локално и я обновява автоматично при промени. След зареждането стават достъпни автоматичното довършване (Ctrl+Space), валидирането на заявката и прегледът на възможните грешки преди изпращане.

# GraphQL заявка с променливи в Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Плъгини и разширяване на възможностите

Insomnia Plugin Hub съдържа над 100 плъгина, които разширяват функционалността на клиента. Плъгините се инсталират чрез менюто Preferences → Plugins или ръчно чрез npm. Популярните категории включват генериране на тестови данни, експорт в различни формати и персонализирани валидатори на отговори. Всеки плъгин преминава през задължителна модерация преди публикуване в общия хъб на разработчиците.

Популярни плъгини

• insomnia-plugin-faker — генериране на фалшиви данни (име, имейл, телефон) за тестови заявки.
• insomnia-plugin-aws4 — подписване на заявки по AWS Signature Version 4 за работа с Amazon API Gateway и S3.
• insomnia-plugin-utils — помощни средства за работа с дати, хеширане и Base64 кодиране директно в заявките.

Плъгините се пишат на JavaScript и взаимодействат с Insomnia чрез API-то за шаблони (response.*, request.*, environment.*). Разработването на плъгин изисква основни познания по Node.js и публикуване чрез npm пакет с таг insomnia-plugin.

CLI и автоматизация на тестването

Inso CLI — конзолна програма, вградена в Insomnia, за стартиране на заявки и тестове от терминала. Inso стартира отделни заявки или цели колекции, експортира резултатите в JSON и може да се интегрира в CI/CD пайплайни. Командата inso run collection последователно изпълнява всички заявки в колекцията.

Пример за интеграция в GitHub Actions

Inso CLI работи в Docker контейнери и в headless режим, което позволява използването му в GitHub Actions и GitLab CI. Конфигурацията за стартиране се описва в YAML файл с посочване на пътя към експортираната колекция и средата. Поддържат се твърдения за кода на състоянието и тялото на отговора чрез JavaScript скриптове.

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

Интеграция на Insomnia с Git и екипна работа

Insomnia поддържа синхронизация на колекциите чрез Git. Файловете на колекциите се съхраняват във формат JSON и могат да бъдат добавени в хранилището на проекта. Insomnia предоставя вграден Git клиент за преглед на промените, създаване на комити и разрешаване на конфликти при сливане директно от интерфейса.

Настройка на Git синхронизация

За да свържете Git, създайте локална папка с хранилище и я посочете като основна директория в настройките на Insomnia. Приложението автоматично следи промените във файловете на колекцията и ги показва в панела Version Control. Поддържат се стандартни операции: commit, push, pull и преглед на diff между версиите.

Екипна работа чрез Insomnia Cloud

За проекти без Git Insomnia предлага облачна синхронизация чрез Insomnia Cloud. Безплатният тарифен план включва до 3 членове на екипа и автоматично архивиране на колекциите. Платените тарифни планове добавят управление на достъпа, одит на промените и приоритетна поддръжка.

Design Mode и генериране на спецификации

Design Mode в Insomnia позволява създаването на API спецификации във формат OpenAPI 3.0. Режимът работи като визуален редактор: дефинирайте крайни точки и схеми на данни, без да пишете YAML на ръка. Спецификацията може да бъде експортирана в JSON или YAML.

Генериране на колекция от OpenAPI

Insomnia импортира OpenAPI спецификации и създава колекция от заявки за всяка крайна точка. Пътищата и схемите се преобразуват в готови HTTP заявки. Функцията е полезна при интеграция с микросървизи, където спецификацията се съхранява в отделно хранилище на екипа.

Маркиране на заявки

На всяка заявка може да се зададе цветен етикет: red, blue, green, orange, purple. Филтрирането по етикети работи чрез полето за търсене независимо от структурата на папките, което улеснява навигацията в проекти със стотици крайни точки и множество модули.

Design Mode и генериране на спецификации

Design Mode в Insomnia позволява създаването на API спецификации във формат OpenAPI 3.0 директно в приложението. Режимът работи като визуален редактор: дефинирайте крайни точки, схеми на данни и параметри, без да пишете YAML на ръка. Спецификацията може да бъде експортирана в JSON или YAML за публикуване в хранилището.

Генериране на колекция от OpenAPI

Insomnia импортира съществуващи OpenAPI спецификации и автоматично създава колекция от заявки за всяка крайна точка. Пътищата и схемите се преобразуват в готови HTTP заявки с правилни типове данни. Тази функция е полезна при интеграция с микросървизи, където спецификацията се съхранява и поддържа от отделен екип от бекенд разработчици.

Маркиране и филтриране на заявки

За организирането на голям брой заявки Insomnia поддържа маркиране — на всяка заявка може да се зададе цветен етикет: red, blue, green, orange, purple. Филтрирането по етикети работи чрез полето за търсене независимо от структурата на папките, което улеснява навигацията в проекти със стотици крайни точки и множество функционални API модули.