Getting started with Kong Insomnia

Hey folks 👋🏼

For the past week, I had the chance to explore a tool called Insomnia by Kong and thought I'd share my learnings through this blog. So here we go.

Imagine you're a developer, sitting at your desk late at night, surrounded by coffee cups and lines of code. You've been tasked with integrating a new API, but every time you test it, something goes wrong. The errors are vague, the debugging process is tedious, and you start feeling that familiar frustration creep in - you wonder, Isn’t there an easier way to do this?💭

Enter Insomnia – but don’t let the name fool you! This isn’t the kind of insomnia that keeps you awake at night; in fact, it’s here to save you from sleepless nights. 🤪

You quickly realize that Insomnia isn't just another API client – it’s a one-stop shop. You can Design, Debug, and Test APIs all in one go.

No more jumping between different tools to authenticate, debug, and test your requests. With Insomnia’s built-in authentication helpers, you can set up OAuth, Basic Auth, or any token-based security in just a few clicks.

You can set up environment variables for different stages – from development to production – keeping your workspace organized and neat. No more fumbling around changing URLs manually.

But wait, there’s more: your API isn't live yet, and you need to simulate responses. Not a problem! You use Insomnia to mock APIs and simulate server behaviour, allowing you to test without ever having to spin up a backend. With the real-time collaboration feature, your entire team can jump in, test, and debug right alongside you.

As you watch your API deliver a smooth "200 OK" ✅ and your tests succeed one after another, you feel a sense of relief and accomplishment. Insomnia isn’t just a tool, it’s your secret weapon against the chaos of API development.

And there's even more! Here are the storage options you can use for your projects, collections, specs, and other files:

• Local Vault: Store your collections, design specs, and other resources locally.

• Cloud Sync: Collaborate in the cloud with end-to-end encryption (E2EE) for free.

• Git Sync: Use any third-party Git repository to store all your files.

So, how do you get started?

Getting started is easy! Insomnia is available for Mac, Windows, and Linux, so no matter what platform you’re on, you’re covered. You can download it from their website: https://insomnia.rest/download

We'll be trying Insomnia together 🌱

Now, let's send our first request! 🎊

Make a new collection by clicking the + icon in the sub-menu named Collections and name it Demo.

You'll see something like this. Now, let's create a new HTTP request. I've already made an API you can use to test it out :D (but feel free to use any API you like! 😉)

Here's the Github repo

I've made a basic API that handles signup and login. Here's how it works:

1. [GET] Request to check if the server is running or not.

2. [POST] Sign up a new user with a username and password.

3. [POST] Log in with the same credentials, and you'll get an access token. This means the user is authenticated.

4. [GET] Use the access token to access the protected route.

📌 Click on New HTTP Request

Let's try the GET request and check out the preview. Use this API path: https://insomnia-demo.vercel.app/ and hit SEND. This is the API which I developed

Note: It's an open route.

This means that anyone with the URL of the API can send requests to it and receive a response, without needing credentials like an API key, token, or login.

YAY 🎉, the server is up and running!

What else do we see? 👀

1. Status 200 OK: Right away, you can see if your request worked.

2. Execution Time: Check how long your request took – super handy for performance insights.

3. Headers: Get a detailed look at request and response headers, which is great for debugging and understanding how the API works.

4. Response Size: See the size of the response, whether it’s 24B or 24MB – every byte counts!

5. Mock Servers: No real server to test with? No worries. You can mock API responses and simulate server behavior for testing.

6. Cookies: Keep an eye on cookies (if any) that get sent or received during the request, making session management a breeze.

Let's test the other APIs that we mentioned before and see if they work.

Create a new request. For the quick tutorial, we'll be doing HTTP requests, but you have so many options. You can also organize your interface using folders to keep your APIs tidy📂

We'll be signing up the user now. Use this API path https://insomnia-demo.vercel.app/signup

Okay, so I made this POST request. Did you notice something? The domain https://insomnia-demo.vercel.app is used everywhere.

You can set up environment variables to reuse values across multiple requests. Common examples include base URLs, authentication tokens, and resource IDs. This approach helps keep your requests organized and avoids repetitive configuration, making your API testing more efficient. Let's set one up.

Head over to the Base Environment option and click the pencil ✏️

Put this in the body for our tutorial
Note: the variable name can be anything as you would like

     {
       "host": "insomnia-demo.vercel.app"
     }

And that's it, you're done 👍

Add the BODY. There are a ton of options to choose from, but I'm going with JSON.

{
    "username": "Joey",
    "password": "danse123"
}

User is registered successfully ✅

Now let's Log in the user. Use this API Path: https://insomnia-demo.vercel.app/login

Use the same login credentials which you did for Sign up. YAY, we got the access token!

Here are the header details

📌 Final step, let's access the protected route and see if it works.

A protected route in an API is an endpoint that requires authentication and/or authorization to access.

Use this API Path: https://insomnia-demo.vercel.app/protected

We have a few Auth options, but for this example, we're going with the Bearer token.

Voila! Using the access token, we got access to the protected route!

Now, let's check out some quick scenarios we forgot to test 🧪

📌 Scenario 1: What if the route path isn't correct?

📌 Scenario 2: What if the password is wrong?

📌 Scenario 3: What if we try to log in but the user doesn't exist?

📌 Scenario 4: What if the access token has expired or is wrong?

All the scenarios work just like we expected, and the preview tool gives the right status codes! It was super easy and user-friendly to use.

Oh, and there's another awesome feature I want to mention: Import/Export 👾

From the Document or Collection name dropdown menu, select Import/Export.

Here's the complete YAML file of the environment we set up in Insomnia.

Also, if you want to work with others in the environment, you can just invite them.

Which will look something like this. Pretty cool, right?

And there you have it, we explored Insomnia together 🦸🏻‍♀️

If you haven’t tried Insomnia yet, now’s the perfect time to see how it can boost your development experience. Download it, check out its features, and see how it changes your approach to API testing.

Got questions or stories to share? Drop them in the comments below – I’d love to hear how Insomnia is working for you. 😍

I'll be back with more tutorials on Insomnia, so stay tuned and see you in the next one.

Also, check out our Twitter/X spaces that we host weekly!! 😉

Wait.. have you heard about the Kong API Summit?

The API Summit by Kong unites top minds in the API space to share best practices for building, running and governing APIs across any environment. Learn how to achieve zero-trust security, enhance developer productivity, reduce operational overhead and maximise ROI.

Sign up for the Kong API Summit, which will be held virtually from 11-12 September! And attend talks & keynotes from some amazing speakers onboard! 😍