Insomnia - Kompletny Przewodnik po Desktop API Client

# Homebrew (recommended)
brew install --cask insomnia

# Or download from insomnia.rest

# Winget
winget install Insomnia.Insomnia

# Chocolatey
choco install insomnia-rest-api-client

# Or download installer from insomnia.rest

# Ubuntu/Debian
# Add repository
echo "deb [trusted=yes arch=amd64] https://download.konghq.com/insomnia-ubuntu/ default all" \
  | sudo tee /etc/apt/sources.list.d/insomnia.list

# Install
sudo apt update && sudo apt install insomnia

# Snap
sudo snap install insomnia

# Fedora
sudo dnf install insomnia

# Arch Linux (AUR)
yay -S insomnia-bin

# After installation you can:

# 1. Use Scratch Pad (offline, no account)
# Full functionality, local data storage

# 2. Sign in (cloud sync)
# Sync across devices

# 3. Connect to Git (self-hosted sync)
# Version control and collaboration via Git

Method: GET
URL: https://api.example.com/users

Headers:
  Accept: application/json
  Authorization: Bearer {{ _.authToken }}

# Response (200 OK)
{
  "users": [
    {"id": 1, "name": "John", "email": "john@example.com"},
    {"id": 2, "name": "Anna", "email": "anna@example.com"}
  ],
  "total": 2,
  "page": 1
}

Method: POST
URL: {{ _.baseUrl }}/users

Headers:
  Content-Type: application/json
  Authorization: Bearer {{ _.authToken }}

Body (JSON):
{
  "firstName": "Peter",
  "lastName": "Smith",
  "email": "peter@example.com",
  "role": "developer",
  "department": "Engineering"
}

# Response (201 Created)
{
  "id": "user_abc123",
  "firstName": "Peter",
  "lastName": "Smith",
  "email": "peter@example.com",
  "role": "developer",
  "department": "Engineering",
  "createdAt": "2025-01-25T10:30:00Z"
}

Method: PATCH
URL: {{ _.baseUrl }}/users/{{ _.userId }}

Headers:
  Content-Type: application/json
  Authorization: Bearer {{ _.authToken }}

Body:
{
  "role": "senior-developer",
  "department": "Platform Engineering"
}

# Response (200 OK)
{
  "id": "user_abc123",
  "firstName": "Peter",
  "lastName": "Smith",
  "role": "senior-developer",
  "department": "Platform Engineering",
  "updatedAt": "2025-01-25T11:00:00Z"
}

Method: DELETE
URL: {{ _.baseUrl }}/users/{{ _.userId }}

Headers:
  Authorization: Bearer {{ _.authToken }}

# Response (204 No Content)

Method: GET
URL: {{ _.baseUrl }}/products

Query:
  category: electronics
  minPrice: 100
  maxPrice: 1000
  inStock: true
  sort: price
  order: asc
  page: 1
  limit: 20

# Insomnia automatically builds the URL:
# https://api.example.com/products?category=electronics&minPrice=100&maxPrice=1000&inStock=true&sort=price&order=asc&page=1&limit=20

# 1. JSON (application/json)
{
  "name": "Product",
  "price": 99.99
}

# 2. Form URL Encoded (application/x-www-form-urlencoded)
name=Product&price=99.99

# 3. Multipart Form Data (multipart/form-data)
--boundary
Content-Disposition: form-data; name="file"; filename="image.png"
Content-Type: image/png

[binary data]
--boundary
Content-Disposition: form-data; name="description"

Product image
--boundary--

# 4. XML (application/xml)
<?xml version="1.0"?>
<product>
  <name>Product</name>
  <price>99.99</price>
</product>

# 5. Plain Text (text/plain)
Raw text content

# 6. Binary (for file upload)
[File selector]

// Base Environment (shared across all)
{
  "apiVersion": "v1",
  "timeout": 30000,
  "retries": 3
}

// Development Environment
{
  "baseUrl": "http://localhost:3000/api",
  "authToken": "dev-token-12345",
  "debugMode": true,
  "database": "dev_db",
  "logLevel": "debug"
}

// Staging Environment
{
  "baseUrl": "https://staging-api.example.com",
  "authToken": "staging-token-67890",
  "debugMode": true,
  "database": "staging_db",
  "logLevel": "info"
}

// Production Environment
{
  "baseUrl": "https://api.example.com",
  "authToken": "{{ process.env.PROD_API_TOKEN }}",
  "debugMode": false,
  "database": "prod_db",
  "logLevel": "error"
}

# In URL
URL: {{ _.baseUrl }}/{{ _.apiVersion }}/users

# In Headers
Authorization: Bearer {{ _.authToken }}
X-Debug-Mode: {{ _.debugMode }}

# In Body
{
  "config": {
    "database": "{{ _.database }}",
    "timeout": {{ _.timeout }}
  }
}

# System environment variables
{{ process.env.API_KEY }}

# Timestamp
{{ timestamp }}

# UUID
{{ uuid }}

// Built-in template tags in Insomnia:

{{ timestamp }}           // Unix timestamp: 1706180000
{{ timestamp:iso }}       // ISO date: 2025-01-25T10:30:00.000Z
{{ uuid }}                // UUID v4: f47ac10b-58cc-4372-a567-0e02b2c3d479
{{ base64:encode }}       // Base64 encode
{{ base64:decode }}       // Base64 decode
{{ hash:sha256 }}         // SHA256 hash
{{ now:YYYY-MM-DD }}      // Formatted date

// Response reference (for chaining)
{% response 'body', 'req_login', '$.token' %}
{% response 'header', 'req_login', 'X-Request-Id' %}
{% response 'status', 'req_login' %}

// Prompt (ask user)
{% prompt 'Enter API Key', 'api-key', false %}

// File (load from file)
{% file './data/payload.json' %}

// Scenario: Login → Profile → Update

// 1. Login Request
POST {{ _.baseUrl }}/auth/login
Body: { "email": "user@example.com", "password": "secret" }
// Response: { "token": "jwt_token_here", "refreshToken": "refresh_here" }

// 2. Profile Request (uses token from Login)
GET {{ _.baseUrl }}/users/me
Headers:
  Authorization: Bearer {% response 'body', 'req_login', '$.token' %}

// 3. Update Request (uses userId from Profile)
PATCH {{ _.baseUrl }}/users/{% response 'body', 'req_profile', '$.id' %}
Headers:
  Authorization: Bearer {% response 'body', 'req_login', '$.token' %}
Body: { "name": "Updated Name" }

// Response from first request:
{
  "data": {
    "user": {
      "id": "user_123",
      "profile": {
        "settings": {
          "theme": "dark",
          "notifications": true
        }
      }
    }
  }
}

// JSONPath expressions:
{% response 'body', 'req_1', '$.data.user.id' %}
// Result: "user_123"

{% response 'body', 'req_1', '$.data.user.profile.settings.theme' %}
// Result: "dark"

{% response 'body', 'req_1', '$.data.user.profile.settings.*' %}
// Result: ["dark", true]

// Environment with dynamic values
{
  "authToken": "{% response 'body', 'req_login', '$.token' %}",
  "userId": "{% response 'body', 'req_login', '$.user.id' %}",
  "sessionId": "{% response 'header', 'req_login', 'X-Session-Id' %}"
}

// Now all requests use these values:
Authorization: Bearer {{ _.authToken }}
X-User-Id: {{ _.userId }}
X-Session-Id: {{ _.sessionId }}

# Endpoint: {{ _.baseUrl }}/graphql

query GetUsers($first: Int!, $after: String) {
  users(first: $first, after: $after) {
    edges {
      node {
        id
        name
        email
        avatar
        createdAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Variables
{
  "first": 10,
  "after": null
}

mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      name
      email
    }
    errors {
      field
      message
    }
  }
}

# Variables
{
  "input": {
    "name": "John Smith",
    "email": "john@example.com",
    "password": "securePassword123"
  }
}

# Insomnia supports GraphQL subscriptions via WebSocket

subscription OnMessageReceived($channelId: ID!) {
  messageReceived(channelId: $channelId) {
    id
    content
    sender {
      name
      avatar
    }
    createdAt
  }
}

# Variables
{
  "channelId": "channel_123"
}

# Insomnia automatically establishes WebSocket connection
# and displays incoming messages

# Insomnia automatically fetches schema from:
# - Introspection query
# - URL to schema file
# - Local .graphql file

# This gives you:
# - Autocomplete for fields and types
# - Real-time query validation
# - Inline documentation
# - Argument hints

# Method 1: Reflection (automatic)
Server URL: grpc.example.com:443
Use Server Reflection: Yes

# Method 2: Proto file
Server URL: grpc.example.com:443
Proto File: ./protos/service.proto

# Method 3: Proto directory
Server URL: grpc.example.com:443
Proto Directory: ./protos/

// user_service.proto
service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc CreateUser (CreateUserRequest) returns (User);
}

message GetUserRequest {
  string id = 1;
}

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  int32 age = 4;
}

// Request (Insomnia)
Service: UserService
Method: GetUser

Message:
{
  "id": "user_123"
}

// Response
{
  "id": "user_123",
  "name": "John Smith",
  "email": "john@example.com",
  "age": 30
}

service StreamService {
  rpc StreamEvents (StreamRequest) returns (stream Event);
}

message StreamRequest {
  string channel = 1;
}

message Event {
  string id = 1;
  string type = 2;
  string data = 3;
  int64 timestamp = 4;
}

// Request
{
  "channel": "notifications"
}

// Streaming responses (displayed in real-time)
← {"id":"1","type":"message","data":"Hello","timestamp":1706180000}
← {"id":"2","type":"notification","data":"Update","timestamp":1706180001}
← {"id":"3","type":"alert","data":"Warning","timestamp":1706180002}

service ChatService {
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message ChatMessage {
  string user = 1;
  string content = 2;
  int64 timestamp = 3;
}

// Send messages
→ {"user":"john","content":"Hello!","timestamp":1706180000}
→ {"user":"john","content":"Anyone there?","timestamp":1706180005}

// Receive responses
← {"user":"anna","content":"Hi John!","timestamp":1706180002}
← {"user":"anna","content":"Yes, I'm here","timestamp":1706180007}

# Insomnia Design View

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
  description: |
    API for an e-commerce application.
    Handles users, products, and orders.
  contact:
    name: API Support
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: http://localhost:3000/v1
    description: Development

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

    post:
      summary: Create user
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - email

    CreateUserInput:
      type: object
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
      required:
        - name
        - email
        - password

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

# After defining the OpenAPI spec, Insomnia automatically:

1. Generates a Collection with all endpoints
2. Creates example requests
3. Sets up validation based on schemas
4. Generates documentation
5. Creates a mock server (preview)

# You can also import existing specs:
File → Import → OpenAPI/Swagger

// Test script (JavaScript)
// Runs after each response

// Check status code
const response = insomnia.response;

if (response.status !== 200) {
  throw new Error(`Expected 200, got ${response.status}`);
}

// Check body
const body = JSON.parse(response.body);

if (!body.users || !Array.isArray(body.users)) {
  throw new Error('Expected users array in response');
}

if (body.users.length === 0) {
  throw new Error('Expected at least one user');
}

// Check structure
const user = body.users[0];
const requiredFields = ['id', 'name', 'email'];

for (const field of requiredFields) {
  if (!user[field]) {
    throw new Error(`Missing required field: ${field}`);
  }
}

// Check response time
if (response.responseTime > 1000) {
  throw new Error(`Response too slow: ${response.responseTime}ms`);
}

console.log('All tests passed!');

// Insomnia supports Chai assertions

const { expect } = require('chai');

const response = insomnia.response;
const body = JSON.parse(response.body);

// Status assertions
expect(response.status).to.equal(200);
expect(response.status).to.be.within(200, 299);

// Body assertions
expect(body).to.have.property('users');
expect(body.users).to.be.an('array');
expect(body.users).to.have.lengthOf.at.least(1);

// User structure
const user = body.users[0];
expect(user).to.include.all.keys('id', 'name', 'email');
expect(user.email).to.match(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);

// Headers
expect(response.headers).to.have.property('content-type');
expect(response.headers['content-type']).to.include('application/json');

// Response time
expect(response.responseTime).to.be.below(500);

# Run all tests in a collection

# From GUI:
# 1. Open Collection
# 2. Click "Run" button
# 3. Select Environment
# 4. Click "Run Tests"

# From CLI (Inso):
npm install -g insomnia-inso

# Run tests
inso run test "My Collection" --env "Production"

# Output:
# Running tests for "My Collection"
#   ✓ GET /users (234ms)
#   ✓ POST /users (456ms)
#   ✓ GET /users/:id (123ms)
#   ✗ DELETE /users/:id (89ms)
#     Error: Expected 204, got 403
#
# Results: 3 passed, 1 failed

# .github/workflows/api-tests.yml
name: API Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Inso CLI
        run: npm install -g insomnia-inso

      - name: Run API Tests
        run: |
          inso run test "API Tests" \
            --src insomnia.yaml \
            --env "CI Environment" \
            --reporter junit \
            --output test-results.xml
        env:
          API_BASE_URL: ${{ secrets.API_BASE_URL }}
          API_TOKEN: ${{ secrets.API_TOKEN }}

      - name: Upload Test Results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: test-results.xml

# Insomnia Plugin Hub
# Preferences → Plugins → Browse Plugins

# Popular plugins:
# - insomnia-plugin-jwt - JWT decoding
# - insomnia-plugin-hash - Hashing functions
# - insomnia-plugin-file - File operations
# - insomnia-plugin-random - Random data generators
# - insomnia-plugin-base64 - Base64 encode/decode

// insomnia-plugin-custom-auth/main.js

module.exports.templateTags = [
  {
    name: 'customAuth',
    displayName: 'Custom Auth Token',
    description: 'Generates custom authentication token',

    args: [
      {
        displayName: 'API Key',
        type: 'string',
        defaultValue: ''
      },
      {
        displayName: 'Secret',
        type: 'string',
        defaultValue: ''
      }
    ],

    async run(context, apiKey, secret) {
      const crypto = require('crypto');
      const timestamp = Date.now().toString();
      const message = `${apiKey}:${timestamp}`;

      const hmac = crypto.createHmac('sha256', secret);
      hmac.update(message);
      const signature = hmac.digest('hex');

      return `${apiKey}:${timestamp}:${signature}`;
    }
  }
];

// Usage in Insomnia:
// Authorization: {% customAuth 'my-api-key', 'my-secret' %}

// insomnia-plugin-logger/main.js

module.exports.requestHooks = [
  (context) => {
    const { request } = context;

    // Log request details
    console.log(`[REQUEST] ${request.method} ${request.url}`);
    console.log('[HEADERS]', JSON.stringify(request.headers, null, 2));

    // Modify request
    request.setHeader('X-Request-Id', generateUUID());
    request.setHeader('X-Timestamp', Date.now().toString());
  }
];

module.exports.responseHooks = [
  (context) => {
    const { response } = context;

    // Log response
    console.log(`[RESPONSE] ${response.status} ${response.statusText}`);
    console.log(`[TIME] ${response.elapsedTime}ms`);

    // Check for errors
    if (response.status >= 400) {
      console.error('[ERROR]', response.body);
    }
  }
];

# npm
npm install -g insomnia-inso

# Homebrew (macOS)
brew install inso

# Check version
inso --version

# Export spec to file
inso export spec "My API" --output api-spec.yaml

# Lint OpenAPI spec
inso lint spec api-spec.yaml

# Run tests
inso run test "API Tests" --env "Production"

# Generate Kong configuration
inso generate config "My API" --type kong --output kong.yaml

# Script mode (from file)
inso script run my-script

# Generate Kong configuration from OpenAPI
inso generate config "My API" \
  --type kong \
  --output kong.yaml

# Generated kong.yaml
_format_version: "2.1"
services:
  - name: my-api
    url: https://api.example.com
    routes:
      - name: users-list
        paths:
          - /v1/users
        methods:
          - GET
        strip_path: false
    plugins:
      - name: rate-limiting
        config:
          minute: 100
      - name: jwt

# 1. Create a new project in Insomnia
# 2. Click "Setup Git Sync"
# 3. Enter repository URL:
#    git@github.com:username/api-collection.git

# Repository structure:
api-collection/
├── .insomnia/
│   ├── ApiSpec/
│   │   └── spc_xxx.yml        # OpenAPI specs
│   ├── Environment/
│   │   ├── env_base.json      # Base environment
│   │   ├── env_dev.json       # Dev environment
│   │   └── env_prod.json      # Prod environment
│   ├── Request/
│   │   ├── req_login.json     # Login request
│   │   ├── req_users.json     # Users request
│   │   └── req_products.json  # Products request
│   ├── RequestGroup/
│   │   ├── fld_auth.json      # Auth folder
│   │   └── fld_api.json       # API folder
│   └── Workspace/
│       └── wrk_main.json      # Main workspace
└── README.md

# Developer 1: Adding a new endpoint
# 1. Pull latest changes
git pull origin main

# 2. Create branch
git checkout -b feature/add-orders-endpoint

# 3. Edit in Insomnia (automatic sync)

# 4. Commit and push
git add .
git commit -m "Add orders endpoint"
git push origin feature/add-orders-endpoint

# 5. Create Pull Request

# Developer 2: Review and merge
# 1. Pull branch
git fetch origin
git checkout feature/add-orders-endpoint

# 2. Open in Insomnia and test

# 3. Merge after approval
git checkout main
git merge feature/add-orders-endpoint
git push origin main

# Everyone: Sync
# Insomnia automatically detects changes and synchronizes

Authorization Type: Basic Auth
Username: api_user
Password: api_secret

# Insomnia generates:
Authorization: Basic YXBpX3VzZXI6YXBpX3NlY3JldA==

Authorization Type: Bearer Token
Token: {{ _.authToken }}

# Header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Authorization Type: OAuth 2.0

# Grant Type: Authorization Code
Authorization URL: https://auth.example.com/authorize
Token URL: https://auth.example.com/token
Client ID: {{ _.clientId }}
Client Secret: {{ _.clientSecret }}
Redirect URL: insomnia://oauth/callback
Scope: read write profile

# Insomnia handles the flow automatically:
# 1. Opens browser for authorization
# 2. Receives callback with code
# 3. Exchanges code for token
# 4. Uses token in requests

Authorization Type: AWS IAM v4

Access Key ID: {{ _.awsAccessKey }}
Secret Access Key: {{ _.awsSecretKey }}
Region: eu-central-1
Service: execute-api

# Optional:
Session Token: {{ _.awsSessionToken }}

# Insomnia automatically generates:
# - Authorization header (AWS4-HMAC-SHA256)
# - X-Amz-Date
# - X-Amz-Security-Token (if using STS)

# Request
Ctrl/Cmd + Enter       # Send request
Ctrl/Cmd + Shift + Enter  # Send and download response
Ctrl/Cmd + R           # Refresh/Resend

# Navigation
Ctrl/Cmd + 1-9         # Switch between requests
Ctrl/Cmd + E           # Toggle Environment selector
Ctrl/Cmd + Shift + E   # Manage Environments
Ctrl/Cmd + P           # Quick switch (fuzzy search)

# Edit
Ctrl/Cmd + D           # Duplicate request
Ctrl/Cmd + Shift + D   # Duplicate folder
Ctrl/Cmd + Delete      # Delete request
Ctrl/Cmd + N           # New request
Ctrl/Cmd + Shift + N   # New folder

# View
Ctrl/Cmd + \           # Toggle sidebar
Ctrl/Cmd + Shift + \   # Toggle response panel
Ctrl/Cmd + ,           # Preferences
F11                    # Fullscreen

# Format
Ctrl/Cmd + Shift + F   # Format JSON/XML
Tab                    # Indent
Shift + Tab            # Outdent