insomnia

Insomnia

Insomnia is the lightweight alternative to Postman. v9.0+ focuses on Local-First philosophy (Local Vault) and Git Sync.

When to Use

REST, GraphQL & gRPC API Design and Debugging: Modern, lightweight desktop API client with environment chaining.
Inso CLI Automation for CI/CD: Running automated API test suites and linting OpenAPI specifications in pipelines.
Environment & Variable Chaining: Extracting tokens from login endpoints and injecting them into subsequent requests.
Git-Sync Team Collaboration: Versioning API collections, design documents, and tests directly in Git repositories.

Quick Start

// Insomnia Base Environment Configuration
{
  "base_url": "https://api.staging.example.com/v1",
  "auth_token": "Bearer eyJhbGciOi...",
  "tenant_id": "tenant_1234"
}

Core Concepts

Environment Variables & Chained Request Responses

Extracting bearer token from authentication response:

// In Sub-Environment configuration
{
  "base_url": "https://api.staging.example.com",
  "client_id": "app_client_prod",
  "auth_token": "{% response 'body', 'req_login_01', 'b64::JC5hY2Nlc3NfdG9rZW4=::46b', 'no-history', 60 %}"
}

Subsequent requests reference {{ base_url }}/v1/users with header Authorization: Bearer {{ auth_token }}.

Inso CLI Test Execution in CI Pipelines

Running automated API test collections headlessly:

# Lint OpenAPI specification file
inso lint spec "Company API Spec"

# Run automated functional test suite against staging environment
inso run test "User Lifecycle Test Suite" --env "Staging" --ci

gRPC Service Invocation

Calling gRPC methods with server reflection:

Create new request -> Select gRPC.
Enter server URL: grpc.infra.internal:50051.
Enable Server Reflection to auto-load Protobuf method definitions.
Input JSON payload and click Send to stream responses.

Common Patterns

Automated CI Collection Testing with Inso CLI

Problem: Run Insomnia API tests automatically inside CI/CD pipelines.
Solution: Execute tests via inso CLI.

# Install inso CLI
npm install -g insomnia-inso

# Run test suite headlessly in CI
inso run test "User API Test Suite" --env "Staging" --ci

Best Practices

Do:

Sync Insomnia collections to Git repositories for version control and peer review of API changes.
Use Inso CLI in CI/CD pipelines to validate OpenAPI specifications and run regression tests.
Organize environments hierarchically (Base Environment -> Staging, Production sub-environments).
Use response chaining ({% response ... %}) to eliminate manual copy-pasting of auth tokens.

Don't:

Store plaintext production credentials in public Git-synced collections.
Skip OpenAPI linting; maintain clean, valid specs that generate accurate SDKs.
Duplicate request URLs across endpoints; reference {{ base_url }} consistently.

Troubleshooting

Error	Cause	Solution
`SSL Certificate validation failed in Insomnia`	Self-signed SSL certificate in local development.	Uncheck "Validate SSL certificates" in Insomnia Preferences > General.
`Template tag failed: Request has no response`	Chained request hasn't been executed yet.	Execute the referenced upstream request (`req_login`) once.
`CORS Error in Insomnia Web Client`	Web version subject to browser CORS policies.	Use desktop native Insomnia client or configure CORS proxy.

References

Insomnia Documentation