Insomnia Tutorial – Testing and debugging APIs (Tutorial)

Need an introduction to Insomnia?

This Insomnia tutorial will show you how to effectively test and debug APIs.

Let’s get started!

What is Insomnia?

This programme is a test software for an Application Programming Interface (API). A backend developer of software uses it to address REST / GraphQL application interfaces.

The software allows a request to be precisely predefined and the interface responds to this request. The programme helps with debugging, reproducing and testing backend software.

When a normal browser user requests a web page, the user makes an HTTP GET request to obtain a web page. Other HTTP request types such as POST, PUT, DELETE and custom types are possible. These cannot be easily mapped using a browser.

Why use the programme?

Clarity

If you want to test several interfaces at the same time, the software is a must for you. Group requests by topic, create your own projects for different software and use the history for past requests.

Automation

Instead of creating and sending each request individually, you can save any configuration and send requests against your API. If you want to make sure that old features / REST interfaces still work for a release, you can execute them.

Deep insights

Not only content is relevant, but also the header content.

The HTTP headers provide the framework:

• What content should be transferred and how?
• What security regulations must the browser observe?
• How should caching take place?

The tool allows you to create and modify your own headers.

Insomnia Guide

Install

You can download Insomnia from the manufacturer’s website as an .exe and install it in Windows. Linux systems can be supplied with Flatpak.

flatpak install flathub rest.insomnia.Insomnia

Alternatively, add the new software as a PPA repo to the package manager apt-get:

# Add to sources echo "deb [trusted=yes arch=amd64] https://download.konghq.com/insomnia-ubuntu/ default all" \ | sudo tee -a /etc/apt/sources.list.d/insomnia.list 
# Refresh repository sources and install Insomnia 
sudo apt-get update 
sudo apt-get install insomnia

First steps in Insomnia

The software welcomes you with a dashboard.

Here you can create or import projects. Some APIs give you a JSON, which you can import into the software. This file imports all available requests with many examples and internal abbreviations and authentication options.

First create a project by clicking on Create. Select the request collection. Name the project like the API you want to test.

You can create a new request in the left-hand column. Don’t forget to give it a descriptive name by double-clicking on the request. clicking “New Request” 20 times won’t get you anywhere.

Configure request

In the top centre, you can select other methods instead of HTTP GET. Many people don’t realise that you can also define your own. As a rule, however, these should be sufficient for the standard operations Create, Update, Read and Delete.

You can enter the URL to the right of this. This can be based on a simple string or a string with variables. A variable is a placeholder that you can manage under the “Environments” button. Replace the domain with a variable. When moving the API, you do not have to adapt all requests, but only the variable.

Instead of slapping the GET parameters into the URL, the software provides a form with the parameters in tab 2 below the URL bar. The software assembles the complete URL from the table with the parameter name and the values. This gives you a better overview.

Switch output

As soon as you send the request, you will see the response on the right-hand side. Tab 1 enables the view as raw code (HTML, XML, JSON), a formatted view with highlighting and a browser display (Visual Preview).

Tab 2 shows all response headers. These help you to find problems. A typical error is an incorrect MIME type in the response. Tab 3 contains the cookies sent with the request.

… and the last tab shows you the process of the request. Here you can see the header, content, URL etc. in the sequence in which the application processed them.

By right-clicking on the request name, you can copy the requests, duplicate them or copy them as a terminal CURL command. This procedure saves you a lot of work.

Understanding the authentications

Many application interfaces use authentication to identify companies and individuals, track costs and limit content.

Using tokens correctly

Most APIs work not only with a username and password, but also with tokens and files. After successful authentication, the API can send back a temporary token, for example, which you can use to query the API in the next hour. No third party can read this and the real password is not constantly transferred back and forth.

You can add tokens in the second Auth tab under the URL. You will often find the Bearer Token. This is a long string of random characters.

Use cookies cache

Other APIs set a cookie, which you can find under the Cookies tab.

This form of authentication is the most secure method for modern single page applications (applications from Angular to Ionic). The cookie is a small file that the client saves and is used for authentication like a key.

You do not add cookies to your requests, but the API sends the cookie along with the response. Insomnia unbuckles the cookie on top with every further request.

Check settings

Not everything always runs smoothly with the requests. You do not need to validate TLS certificates in the development environment:

Application > Settings > General > Request / Response → Remove the tick next to Validate Certificates

The HTTP version can cause other problems.

Old / dev servers usually use HTTP 1.2 and HTTP 2 is one of the newer standards, which brings significant speed optimisation. Insomnia does not yet support HTTP/3, but as a developer you should familiarise yourself with the new technology at an early stage.

Further problems are possible if you are working in a corporate network. For developers like you, there are usually proxies that allow you to jump out onto the Internet undisturbed. Some firewalls consider developer traffic to be harmful and block many requests. Enter the connection data to the proxy under

Application > Settings > General > HTTP Network Proxy

.

Alternative Postman

If you don’t like the Insomnia interface, why not use Postman? Postman is another API test tool that offers a similar range of functions. If everyone in your team uses Postman, you should use it too. Only then will you be able to track problems accurately. A jumble of tools is not the best basis for good collaboration.