Insomnia — what it is, REST and GraphQL client in development

What Insomnia is and key features

Insomnia is a cross-platform application (Electron) for sending HTTP requests and debugging APIs. It has been developed by Kong since 2016 as an alternative to Postman with an emphasis on speed and privacy: data is stored locally, cloud synchronization is optional and requires registration.

Interface and navigation

The main window is divided into three columns: on the left is the request tree (Workspace), in the center is the request editor with Params, Headers, Body tabs, on the right is the response panel with Pretty, Raw and Preview modes. Dark theme is enabled by default, and custom themes are supported through CSS variables.

Code generation

Insomnia supports exporting a request to code in 20+ languages and frameworks: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP and others. The generator takes into account headers, the request body and the authentication type, which speeds up API integration into application code.

Insomnia vs Postman: comparing API clients

Insomnia and Postman solve the same task but with different priorities. Insomnia is lighter (~80 MB vs ~300 MB), starts faster and works fully offline without forcing registration. Postman offers a more mature ecosystem with monitoring, mock servers and team workspaces.

Choosing the right tool for the task

For individual development and quick endpoint testing, Insomnia is more convenient thanks to its lightness and the lack of registration. For team work with a shared collection, CI/CD integration and production API monitoring, Postman remains the industry standard.

Organizing workspace and environments

Workspace in Insomnia contains a request tree divided into folders. Each request can be of type HTTP, GraphQL, WebSocket or gRPC. Drag-and-drop, duplication and grouping of requests by color labels are supported. The workspace configuration file is stored in JSON format.

Environment variables with inheritance

Insomnia supports nested environments (Sub Environments) that inherit parent variables. This allows you to define a base URL in the global environment and override only the differing parameters for different environments. Variables are substituted using the syntax {`{`}_variable${`}`}.

// Example of an Insomnia environment structure
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Working with GraphQL in Insomnia

Insomnia provides one of the best GraphQL editors among API clients. The GraphQL Query tab lets you write queries with field autocomplete based on the loaded schema. On the right, documentation on types, fields and arguments is displayed in real time.

Loading the schema and Introspection

The schema is loaded through a GraphQL Introspection request to the endpoint. Insomnia caches the schema locally and automatically updates it when changes occur. After loading, autocomplete (Ctrl+Space), request validation and a preview of possible errors before sending become available.

# GraphQL query with variables in Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Plugins and feature extensions

Insomnia Plugin Hub contains more than 100 plugins that extend the client's functionality. Plugins are installed through the Preferences → Plugins menu or manually through npm. Popular categories include test data generation, export to various formats and custom response validators. Each plugin goes through mandatory moderation before being published to the public developer hub.

Popular plugins

• insomnia-plugin-faker — generation of fake data (name, email, phone) for test requests.
• insomnia-plugin-aws4 — signing requests with AWS Signature Version 4 for working with Amazon API Gateway and S3.
• insomnia-plugin-utils — utilities for working with dates, hashing and Base64 encoding right in requests.

Plugins are written in JavaScript and interact with Insomnia through the templating API (response.*, request.*, environment.*). Developing a plugin requires basic knowledge of Node.js and publishing through an npm package with the insomnia-plugin tag.

CLI and test automation

Inso CLI is a console utility built into Insomnia for running requests and tests from the terminal. Inso runs individual requests or entire collections, exports results to JSON and can integrate into CI/CD pipelines. The inso run collection command sequentially executes all requests in a collection.

Example of GitHub Actions integration

Inso CLI works in Docker containers and headless mode, which allows using it in GitHub Actions and GitLab CI. The launch configuration is described in a YAML file specifying the path to the exported collection and the environment. Assertions on the status code and response body are supported through JavaScript scripts.

# GitHub Actions workflow with 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 integration with Git and team work

Insomnia supports collection synchronization through Git. Collection files are stored in JSON format and can be added to the project repository. Insomnia provides a built-in Git client for viewing changes, creating commits and resolving merge conflicts directly from the interface.

Setting up Git synchronization

To connect Git, create a local folder with a repository and set it as the root directory in Insomnia settings. The application automatically tracks changes in collection files and displays them in the Version Control panel. Standard operations are supported: commit, push, pull and viewing diffs between versions.

Team work through Insomnia Cloud

For projects without Git, Insomnia offers cloud synchronization through Insomnia Cloud. The free plan includes up to 3 team members and automatic backup of collections. Paid plans add access management, change auditing and priority support.

Design Mode and specification generation

Design Mode in Insomnia lets you create API specifications in OpenAPI 3.0 format. The mode works as a visual editor: define endpoints and data schemas without writing YAML by hand. The specification can be exported to JSON or YAML.

Generating a collection from OpenAPI

Insomnia imports OpenAPI specifications and creates a collection of requests for each endpoint. Paths and schemas are converted into ready-made HTTP requests. The feature is useful when integrating with microservices where the specification is stored in a separate team repository.

Request tagging

Each request can be assigned a color label: red, blue, green, orange, purple. Tag filtering works through the search bar regardless of the folder structure, which simplifies navigation in projects with hundreds of endpoints and many modules.

Design Mode and specification generation

Design Mode in Insomnia lets you create API specifications in OpenAPI 3.0 format right inside the application. The mode works as a visual editor: define endpoints, data schemas and parameters without writing YAML by hand. The specification can be exported to JSON or YAML for publishing to repositories.

Generating a collection from OpenAPI

Insomnia imports existing OpenAPI specifications and automatically creates a collection of requests for each endpoint. Paths and schemas are converted into ready-made HTTP requests with correct data types. This feature is useful when integrating with microservices where the specification is stored and maintained by a separate backend development team.

Request tagging and filtering

To organize a large number of requests, Insomnia supports tagging — each request can be assigned a color label: red, blue, green, orange, purple. Tag filtering works through the search bar regardless of the folder structure, which simplifies navigation in projects with hundreds of endpoints and many functional API modules.