kong/insomnia

The open-source, cross-platform API client for GraphQL, REST, WebSockets, SSE and gRPC. With Cloud, Local and Git storage.

Insomnia API Client

Insomnia is an open-source, cross-platform API client for GraphQL, REST, WebSockets, Server-sent events (SSE), gRPC and any other HTTP compatible protocol.

With Insomnia you can:

• Debug APIs using the most popular protocols and formats.
• Design APIs using the native OpenAPI editor and visual preview.
• Test APIs using native test suites.
• Mock APIs will be coming soon in November 2023.
• Build CI/CD pipelines using the native Insomnia CLI for linting and testing.
• Collaborate with others using the many collaboration features to share your projects.

And a lot more! The following storage options are supported for your projects, collections, specs and all other files:

• Local Vault: for local storage of collections, design specs and every other resource.
• Cloud Sync: for cloud collaboration, encrypted and free.
• Git Sync: for Git storage of all files using any 3rd party Git repository.

Get started

Insomnia is available for Mac, Windows, and Linux and can be downloaded from the website:

https://insomnia.rest/download

Account & Subscriptions

You can use Insomnia without an account with Scratch Pad, or you can create an account for free to get access to the full capabilities of the product.

Even with an account, Insomnia only stores your projects and files accordingly to the storage backend that you have selected, which can be Local Vault, Cloud Sync, Git Sync or any combination of them. As such you have the freedom to choose to store sensitive projects locally, while still being able to collaborate on others in the cloud or on Git. It's the best of both worlds.

Premium features and support

Kong Inc. offers commercial subscriptions that enhance Insomnia in a variety of ways. Some of those features include the ability to create organizations for your projects, Enterprise SSO with SAML and OIDC, RBAC when sharing our projects with others, AI capabilities to increase developer productivity when creating, testing and documenting APIs and a lot more.

You can explore all premium plans and get started for free.

Bugs and Feature Requests

Have a bug or a feature request? First, read the issue guidelines and search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.

For more generic product questions and feedback, join the Slack Team.

Contributing

Please read through our contributing guidelines and code of conduct. Included are directions for opening issues, coding standards, and notes on development.

Documentation

Check out our open-source Insomnia Documentation.

Develop Insomnia

Development on Insomnia can be done on Mac, Windows, or Linux as long as you have Node.js and Git. See the .nvmrc file located in the project for the correct Node version.

Initial Dev Setup

This repository is structured as a monorepo and contains many Node.JS packages. Each package has its own set of commands, but the most common commands are available from the root package.json and can be accessed using the npm run … command. Here are the only three commands you should need to start developing on the app.

# Install and Link Dependencies
npm i

# Run Lint
npm run lint

# Run type checking
npm run type-check

# Run Tests
npm test

# Start App with Live Reload
npm run dev

Linux

If you are on Linux, you may need to install the following supporting packages:

Ubuntu/Debian

# Update library
sudo apt-get update

# Install font configuration library & support
sudo apt-get install libfontconfig-dev

Fedora

# Install libcurl for node-libcurl
sudo dnf install libcurl-devel

Also on Linux, if Electron is failing during the install process, run the following

# Clear Electron install conflicts
rm -rf ~/.cache/electron

Windows

If you are on Windows and have problems, you may need to install Windows Build Tools

Editor Requirements

You can use any editor you'd like, but make sure to have support/plugins for the following tools:

• ESLint - For catching syntax problems and common errors
• JSX Syntax - For React components

Develop Inso CLI

• npm i
• Start the compiler in watch mode: npm run inso-start
• Run: ./packages/insomnia-inso/bin/inso -v

Plugins

Search for, discover, and install plugins from the Insomnia Plugin Hub!

Community Projects

• Insomnia Documenter - Generate beautiful API documentation pages using the documenter plugin or your Insomnia export file.
• GitHub API Spec Importer - A complete set of GitHub REST API route specifications that can be imported straight into Insomnia.
• Swaggymnia - Generate Swagger documentation for your existing API in Insomnia.

License

Apache-2.0 © Insomnia

insomnia's Issues

Data Export

Do performance sweep for React/Redux components

• Use reselect for things that need it in App.js
• Stop binding to this in render () all the time
• Don't render Sidebar children so much (most expensive component)

There's still lots that can be done, but this should cover most of it.

Add prompt to opt-in to templating

User experience...

• detect that rendered request differed from original
• prompt the user to enable templating feature for the request
  • continue with render (I know what I'm doing)
  • disable rendering for this request
• provide ability to toggle templating features per request (or per workspace even)

Keyboard Shortcuts

• cmd+Enter (or r) Send request
• cmd+, Settings
• cmd+p (or k) Show request switcher
• cmd+l Focus URL bar
• cmd+m Change HTTP method
• cmd+e Edit environment
• cmd+n New request
• cmd+d Duplicate request
• cmd+\ Toggle sidebar

Only close windows with meta+w on Mac

On Windows and Linux, alt+f4 is the typical way to close windows (needs verification).

Change create request prompt to show folder instead

[Feature] Introductory scripting support

Insomnia should support some sort of scripting for the following tasks.

• Settings environment variables based on response data
• Performing custom authentication
• Chaining requests (maybe)

[Epic] Plugin Framework

Insomnia should support the ability to build full-featured plugins on top of. Due to the low performance requirements that Insomnia plugins will have, HTTP would be an ideal protocol for plugin communication. HTTP-based plugins are not as easy to write or run, but maybe that's not a problem.

How it would work:

• write a web server with certain endpoints to respond to hooks
  • /plugin-info to define plugin behavior
  • /pre-render to set up env and stuff
  • /pre-request to do things like auth and stuff
  • /post-request to handle the response (set env vars, etc)
• app would contact plugins when hooks are triggered
• plugins would respond with certain commands for the app
  • set-env-var
  • add-cookie
  • etc...

Random List of Use Cases

• Custom authentication
• Storing and refreshing authentication tokens
• Computing environment variables

Nunjucks title filter fails on undefined

With no data, this will throw an error: {{ foo.bar.baz | title }}

Click on response time tag to see in raw milliseconds always

Run tests in Electron environment

Now that Insomnia uses native modules (node-libcurl) the tests that require it no longer run. This is because the module needs to be compiled against NodeJS and Electron separately. If we can make it so the tests only ever use the Electron node runtime, we can compile native modules once and leave assume they will work.

Content-Type header being overridden

Bug Report:

insomnia seems to constantly override my Content-Type header I'll set it to [text/xml;charset="utf-8"] and when the response comes back the header on my SEND side is either removed completely or changed to [application/text] and I have to go back in and change it again for each time I hit Send.

Don't autocomplete URLs as often

URLs should only autocomplete if they match the entire URL string as a prefix.

Database file write can corrupt if it's inturrupted

[Improvement] Better import workflow

Right now, importing is weird because there is no feedback on what actually happened. Also, importing data may be destructive, because existing data will be overwritten. Thus, the import functionality should be refactored into something more sensible.

• detect the filetype of the import and show the user whether or not it's supported
• perform a dry run to figure out what will be created/updated
• show dry run results to the user
• let the user select the import type based on results
  • only create new resources
  • only update existing resources (maybe)
  • option to do the whole import as a copy

Add ability to upload client certificates

You can do this using agentOptions of the request library.

var fs = require('fs')
    , path = require('path')
    , certFile = path.resolve(__dirname, 'ssl/client.crt')
    , keyFile = path.resolve(__dirname, 'ssl/client.key')
    , request = require('request');

var options = {
    url: 'https://api.some-server.com/',
    agentOptions: {
        cert: fs.readFileSync(certFile),
        key: fs.readFileSync(keyFile),
        // Or use `pfx` property replacing `cert` and `key` when using private key, certificate and CA certs in PFX or PKCS12 format:
        // pfx: fs.readFileSync(pfxFilePath),
        passphrase: 'password',
        securityOptions: 'SSL_OP_NO_SSLv3'
    }
};

request.get(options);

OAuth with no refresh token doesn't handle expire properly

Bug Report:

My API returns an expires_in field but no refresh token (you are expected to get a new one if it expires). I believe this is valid according to the RFC as both fields are optional with no interdependencies.
However, the acquired token shows up as "Never expires" in Insomnia; I guess that is because there is no refresh token.

Fix request switcher not finding nested folders

Add body type to create request modal

Should ignore response after switch request

Flush input debounce before sending

This is a problem when updating a URL and triggering a send right away.

Potential Solution

• create generic debounce handler
• add hooks to flush the debounce callbacks
• maybe move the debouncing to the database level?
  • could flush debounced writes before every query (send calls do a query)

Don't put equal signs on the query params with no values

Use Reselect for `entities` operations

http://redux.js.org/docs/recipes/ComputingDerivedData.html

[Improvement] Warn about invalid environment variable names

Nunjucks does not allow - in variable names. A common mistake users make is to name variables like my-variable and try to use it as {{ my-variable }}. However, Nunjucks interprets this as "my subtract variable" and causes confusion.

Solution: Show warning in environment editor when a key of the JSON contains characters that are not valid in Nunjucks.

Ideally, this could mark the error inline using Codemirror, but would probably be fine as a global warning (above or below the editor) to start.

Support no-body state in Request Pane

It's confusing when a new user makes a request and the body defaults to a code editor with a tab title of Other. It would be better to default to an empty screen explaining that there is no body selected. This would also make it so the tab could say something like Body instead of Other.

[Improvement] Ability to auto-hide menu bar like on Atom

Apparently, Atom has a setting to "Auto Hide Menu Bar." A LOT of users hate the look of the menu bar so it would be awesome to copy Atom in this regard.

This is only a problem on Windows and Linux because MacOS hides the application menubar at the top of the screen.

Implement React Router

Benefits

• back/forward history
• no need to track active workspace/request (maybe)
• easier to manage "page" state

Switch from PouchDB to LokiJS

Why?

PouchDB required high storage overhead because it requires saving a full history of every document. If we don't necessarily need sync, this is not worth it.

LokiJS

LokiJS has a very similar API to PouchDB (probably simpler) so it should be trivial to drop in.

Wins

• No longer have to debounce user input
• Can use the NPM package
• Can easily persist to file for Dropbox/cloud sync
• Has a changes API that can be used to sync remotely

[Improvement] Refresh OAuth tokens on 401 response

Sometimes developers reset their OAuth server and clear tokens. When this happens, Insomnia fails the request with a 401 and the user has to manually refresh the token. Ideally, the app would see the 401 and attempt to refresh the token automatically.

• Send request with saved token
• See 401 response
• Attempt to refresh the token
• Retry request if refresh succeeded
• Only do this once to prevent infinite fetch loop

Use sidebar children data for request switcher entities

Migrate persisted Redux stores to db models

Sidebar Drag-n-Drop

Should use React DnD

[Improvement] Setting to disable automatic updates

TODO

• Setting to disable update check
• Have a way to trigger update check manually (optional)
• Have a way to automatically check for updates, but not install automatically (optional)

Don't always escape all characters during URL encoding

Characters like ; , and @ are often used in custom URL schemes, so they should not be encoded by default.

Cancel Request

• Add to slow request spinner
• Do by default if change request (maybe?)

Add ability to save to file in code generation

• Save to a file
• Remember location so it can easily be overwritten
• Add real-time sync functionality so you can keep testing it (not sure if actually useful)

Dropdown should be Dropup when near bottom

Multiple requests sent on keyboard shortcut

When sending a request using the keyboard shortcut, sometimes multiple are sent. This is most likely due to improper cleanup of event listeners.

[Improvement] Setting to disable tracking

Right now, Insomnia sends data to Google Analytics. Insomnia should allow the user to opt-out of these things via a setting.

[Feature] Sortable Environments

Environments should be sortable just like the items in the request sidebar.

Do something with RapidAPI

https://rapidapi.com

Response webview doesn't set if not finished loading page yet

Add separate workspace settings

There are a lot of things in settings that don't make sense across multiple workspaces. These settings should be moved to the Workspace model. There are also some new things that would also fit here.

Existing settings to be moved

• name
• follow redirects
• validate SSL
• request timeout

New things to be added

• description (pro)
• color (pro)

Make network tests work again

Version 5.0 switched networking to use libcurl so the nock NodeJS mocking library can no longer be used.

Potential Solution:

• Write a small NodeJS server
• Start server on a random port at the beginning of a test
• Do assertions by making real network requests to the test server

Setting for default indent level

Right now, Insomnia defaults to 4 spaces for an indent but this takes up a lot of horizontal space so it would be nice to have the option to change it to 1 or 2.

Response History

• Add dropdown to show recent responses
• Add ability to switch responses
• Keep track of active response in Redux
• Clear active response on next request

Workspace Management

Better handling of rapid "Send" clicks

Desktop icon is re-added after every update

Ability to share things via Github Gist

• backups
• exports
• generated code
• responses
• etc...