Development Tool

Insomnia

Overview

Insomnia is a simple yet powerful API client developed by Kong Inc. It features a beautiful, intuitive UI and supports a wide range of protocols including GraphQL, REST, WebSocket, gRPC, and SSE. Designed with developer experience in mind, it significantly improves API development and testing workflows.

Details

Insomnia was originally developed by Gregory Schier in 2016 as an open-source, cross-platform API client. Kong Inc. acquired it in 2019 and now offers it as part of the Kong ecosystem through Kong Studio. Insomnia's greatest strength lies in its unified support for multiple API protocols. Beyond REST APIs, it provides comprehensive support for GraphQL queries, WebSocket real-time communication, gRPC services, and Server-Sent Events (SSE) - covering all protocols needed for modern API development. Its GraphQL support is particularly impressive, featuring schema introspection, query completion, syntax highlighting, and response validation specifically tailored for GraphQL development. The flexible storage options include local storage, cloud sync, and Git repository integration, providing excellent flexibility for team development. Since the Kong acquisition, enterprise features have been significantly expanded, including OpenAPI editor, mock server functionality, and seamless integration with Kong Gateway.

Advantages & Disadvantages

Advantages

• Multi-protocol Support: Comprehensive coverage of REST, GraphQL, WebSocket, gRPC, and SSE
• Excellent GraphQL Experience: Rich schema exploration, query completion, and syntax highlighting
• Beautiful UI: Intuitive and visually appealing interface design
• Flexible Storage: Choice between local, cloud, and Git integration options
• Open Source: Free to use with customization possibilities
• Kong Ecosystem: Seamless integration with Kong Gateway and Kong Studio
• Cross-platform: Available on Windows, macOS, and Linux

Disadvantages

• Learning Curve: Multi-featured nature requires time for beginners to master
• Memory Usage: Electron-based architecture can be resource-intensive
• Enterprise Features: Advanced functionality requires paid plans
• Plugin Ecosystem: Limited plugin availability compared to Postman

Reference Links

• Insomnia Official Site
• Kong Insomnia Documentation
• GitHub - Kong/insomnia
• Kong Blog - Insomnia GraphQL Client
• Insomnia Learning Center

Usage Examples

Basic REST Request

# GET request configuration
GET https://api.example.com/users/{{userId}}
Authorization: Bearer {{accessToken}}
Content-Type: application/json

# Environment variables example
{
  "baseUrl": "https://api.example.com",
  "accessToken": "your-jwt-token",
  "userId": "12345"
}

GraphQL Query Execution

# GraphQL query example
query GetUserProfile($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
    posts {
      id
      title
      content
      createdAt
    }
  }
}

# Variables
{
  "userId": "user123"
}

# Headers
{
  "Authorization": "Bearer {{graphqlToken}}",
  "Content-Type": "application/json"
}

WebSocket Real-time Communication

// WebSocket connection setup
URL: wss://api.example.com/chat
Headers: {
  "Authorization": "Bearer {{wsToken}}"
}

// Message sending example
{
  "type": "message",
  "content": "Hello WebSocket!",
  "channel": "general"
}

// Subscription example
{
  "type": "subscribe",
  "channel": "notifications"
}

gRPC Service Calls

// Proto definition file import
// user.proto content example
syntax = "proto3";

service UserService {
  rpc GetUser(UserRequest) returns (UserResponse);
  rpc CreateUser(CreateUserRequest) returns (UserResponse);
}

message UserRequest {
  string user_id = 1;
}

message UserResponse {
  string id = 1;
  string name = 2;
  string email = 3;
}

// gRPC request example
Method: UserService/GetUser
Message: {
  "user_id": "12345"
}

Environment and Script Usage

// Pre-request Script example
const timestamp = Date.now();
request.setVariable("timestamp", timestamp);

// Automatic JWT token acquisition
if (!request.getVariable("accessToken")) {
  const authResponse = await request.send({
    url: "{{baseUrl}}/auth/login",
    method: "POST",
    data: {
      username: request.getVariable("username"),
      password: request.getVariable("password")
    }
  });
  
  const token = authResponse.getBody().access_token;
  request.setVariable("accessToken", token);
}

// Post-response Script example
const response = insomnia.response.getBody();
if (response.user_id) {
  insomnia.environment.set("currentUserId", response.user_id);
}

// Response validation
expect(response.status).to.equal(200);
expect(response.data.email).to.include("@");

Kong Gateway Integration

# Kong Service configuration example
services:
  - name: user-api
    url: https://api.example.com
    
routes:
  - name: user-route
    service: user-api
    paths:
      - /api/users

# Testing via Kong Gateway in Insomnia
GET http://kong-gateway:8000/api/users/{{userId}}
Host: api.example.com
Kong-Debug: 1