DOCSEARCHbyAlgolia
Submit Docs

Insomnia API Client

repository·develop·Indexed 12 days ago

https://github.com/Kong/insomnia

An open-source, cross-platform API client built on Electron for debugging, designing, testing, and mocking REST, GraphQL, and gRPC protocols. The project includes the Insomnia application, the Inso CLI, and supporting packages such as insomnia-api and insomnia-data.

Tokens
51.3K
Snippets
148
Records
222
Agent score
94%

What's inside Insomnia

  1. Overview of Insomnia API Client

    develop

    Insomnia is an open-source, cross-platform API client designed for debugging, designing, testing, and mocking APIs. It supports multiple protocols including GraphQL, REST, WebSockets, Server-Sent Events (SSE), and gRPC.

    Key Capabilities:

    • Debug APIs: Use popular protocols and formats.
    • Design APIs: Native OpenAPI editor and visual preview.
    • Test APIs: Native test suites and collection runner.
    • Mock APIs: Cloud or self-hosted mocking servers.
    • CI/CD: Native Insomnia CLI for linting and testing.
    • Collaboration: Built-in features for team workflows.
    • Extensibility: Support for 3rd party plugins.

  2. Understand the Insomnia Technology Stack

    develop

    Insomnia is a desktop application built using the following core technologies:

    • Runtime: Electron (Chromium runtime with OS access).
    • UI Library: React.
    • Styling: Tailwind CSS.
    • HTTP Client: libcurl via node-libcurl for deep control and debuggability of requests.
    • Database: NeDB (local in-memory database).
    • Code Editor: CodeMirror for syntax highlighting and linting (JSON, GraphQL, XML).
    • CLI Framework: Commander.js (used for the Inso CLI).

  5. Choose between Checkbox and Switch

    develop

    Deciding whether to use a Checkbox or a Switch depends on the user interaction model:

    FeatureUse Checkbox WhenUse Switch When
    Selection TypeMultiple selections allowedSingle on/off toggle
    ContextForm with multiple optionsSettings that apply immediately
    Effect TimingSelection doesn't take effect immediatelyAction happens instantly
    State ComplexityNeed indeterminate stateNeed instant feedback
    ExampleSelect features to enableEnable dark mode

  6. Understand OAuth2 timeline log entries

    develop

    The Insomnia Console provides detailed logs for the OAuth2 lifecycle, prefixed with [oauth2]. These logs help identify exactly where an authentication flow fails.

    Flow Milestones

    • Starting OAuth2 flow (grantType=..., forceRefresh=...)
    • Using existing access token (cached token reuse)
    • Opening authorization window: <origin> or Opening default browser for authorization: <origin>
    • Authorization redirect detected, exchanging code for token
    • Sending token request to <accessTokenUrl>
    • Token received successfully or Received implicit token successfully

    Token Refresh Logs

    • Refreshing token via <accessTokenUrl>
    • Token refreshed successfully
    • Refresh token rejected (401 Unauthorized)
    • Refresh token rejected: invalid_grant - <description>
    • `Failed to refresh token: status=<code

    Error Logs

    • Authorization window error: Authorization window closed (user closed the window)
    • Authorization error: <error> - <description> (provider-side error)
    • Default browser authorization error: <message>
    • Token request failed: <error>
    • OAuth2 flow error: <message>

    Embedded Curl Timeline

    In addition to high-level milestones, the Console includes the full curl debug output from the token endpoint request. This includes connection details, TLS handshakes, request/response headers, and the response body.

  7. Multi-file plugin resolution rules

    develop

    Plugins can be split across multiple files using relative paths (e.g., require('./util') or require('../shared')).

    • Scope: Relative requires resolve from the plugin's own source directory.
    • Isolation: The plugin's own node_modules is never consulted.
    • Loading: Only .js and .json files within the plugin directory are loaded; node_modules and dot-directories (like .git) are skipped.
    • Vetted Libs: A bare require('uuid') will always resolve to the Insomnia-provided vetted registry copy, preventing plugins from shipping their own versions of standard libraries.

  8. Style the LearnMoreLink component

    develop

    You can customize the appearance of the LearnMoreLink component using the className prop or by overriding specific CSS variables.

    Customizing via CSS Variables

    The component relies on the following CSS variables for its theme:

    • --color-font: Controls the link text color.
    • --color-bg: Controls the link background color.

    Customizing via className

    You can apply utility classes (e.g., Tailwind) directly to the component to override styles.

    <LearnMoreLink className="text-[--color-font]!" href="https://insomnia.rest">
  Visit our website
</LearnMoreLink>

  9. Implementing Named Query Helpers

    develop

    Named query helpers should only be added when there is a repeated business need or an actual caller.

    Guidelines:

    • Naming: Name helpers based on the filter they represent (e.g., listByRemoteId(remoteId) or listByOrganizationIds(organizationIds)).
    • Plurality: If a helper needs to support both a single ID and multiple IDs, use a single plural API that accepts string | string[] instead of creating separate singular and plural methods.
    • Avoid Pre-creation: Do not create parallel helper families like countBy... unless they are actively used.
    • Workflow Methods: Name workflow methods based on business intent rather than database mechanics.

  10. How Undo/Redo commands are routed in Insomnia

    develop

    Insomnia reconciles two different undo stacks (the native browser/Electron menu and CodeMirror's internal stack) through a single app-level handler.

    When an Undo or Redo command is issued from the Edit menu, the system routes the command based on the current focus:

    1. CodeMirror Surface: If a CodeMirror editor is focused, the handler calls cm.undo() or cm.redo() directly to drive the CodeMirror history stack.
    2. Other Surfaces: For any other input (like plain text fields), the handler replays the browser's native edit command using execCommand, preserving native undo behavior.

    This logic is implemented in editor-undo.ts and wired via renderer-listeners.ts.

  11. How Insomnia schema migrations work

    develop

    Insomnia uses a dual-versioning approach to ensure data compatibility across different application versions.

    • Backward Compatibility: Older versions of Insomnia can read newer data files because they ignore the schema_version field.
    • Forward Compatibility: Newer versions of Insomnia can read older data files by automatically applying a sequence of transformation functions (migrations) to bring the data up to the latest version.

    The Dual-Versioning Strategy

    To maintain compatibility, Insomnia uses two distinct fields in its YAML data files:

    1. type: This field remains stable (e.g., collection.insomnia.rest/5.0) to ensure older versions recognize the file format.
    2. schema_version: This field indicates the specific feature set and data structure version (e.g., 5.1).

    When importing data, the application detects the schema_version and applies all necessary migrations sequentially until the data matches the current INSOMNIA_SCHEMA_VERSION.

    # Example of a v5.1 data file
type: "collection.insomnia.rest/5.0"  # Stable type for backward compatibility
schema_version: "5.1"               # Specific version for feature support
name: "My Collection"
collection:
  - name: "My Request"
    headers:
      - name: "Content-Type"
        value: "application/json"

  12. Explore the Insomnia Project Structure

    develop

    The project uses npm workspaces to manage multiple packages. Key locations include:

    • /packages: Contains related packages consumed by the main app or external users.
    • /packages/insomnia-data: Contains shared data models, model services, database adapters, and common data utilities used by both the app and the CLI.
    • /packages/insomnia: The main entry point for the application.
    • /packages/insomnia-inso: The Inso CLI package.
    • /packages/insomnia-smoke-test: Contains the smoke testing suite.