How to use Insomnia to Test API Endpoints

Katie McKnight — Fri, 18 Oct 2019 02:05:16 +0000

So you're building an app that makes various HTTP requests, eh? You know how to make the API calls, whether you're using a library or good ole .fetch(). But without the ability to test your endpoints, you're bound to run into some issues. Testing endpoints will save time, prevent potential errors (and lots of stress!), and give you a better relationship/understanding with your API.

In this article I'll be using Insomnia to demonstrate how to do this. However, there are more options out there (a popular choice being Postman). Feel free to try different platforms to see which one you like best. 😄

Step 1: Install Insomnia

Head over to the official Insomnia website to install it on your machine. There are directions to prompt you once you're there.

Step 2: Check your API Docs

Hopefully your API has a nice set of docs to guide you through this process. Nothing beats some killer docs. Read through them and figure out what you'll need to make each request. What's the base URL? Are there any params or headers required? Do you need a request body and, if so, is it in JSON format? Etcetera, etcetera.

Once you're more familiar with the functionality of your API, go ahead and open up Insomnia.

Step 3: Make your 1st HTTP GET Request w/ Insomnia

Once the app is open, you'll see a mostly "blank" workspace. To begin making requests click the plus icon, which will trigger a dropdown giving you the option to either make a New Request or create a New Folder. Let's make a folder, specific to our project.

Name the folder however you'd like. I usually use the project name. Or, if it's a large project, you may want to use the entire workspace and have various folders within it... the organization is completely up to you.

I'm going to use an API that I built to demonstrate making HTTP requests that cover all CRUD functionality. Request bodies should be in JSON format, and other than register & login, the routes require an Authorization header with a JWT (JSON Web Token) as the value. You can find the docs here if you're interested. This project was called Trip Split, so that's what I'll title my folder.

Now that we have our folder made, we can make our first request. Click the down arrow next to the folder name to see a list of options. Right now we're wanting to make a New Request.

I like to run a "Sanity Check" to see if the server is up. I'll use that as the title for my request then click CREATE. Your Insomnia app should look something like this now:

You can see in the top bar that there's a place to select the type of request you want to make, an input for the URL/endpoint, and a SEND button.

I want to make a GET request, so that's what I'll select. Then I'll put the base URL followed by the endpoint in the input (circled in green below). This request won't have a body, header, or anything else, so I can go ahead and hit SEND.

AWESOME, sweet success. You can see the status of your request (here it was 200, which means it was successful), the time it took to complete, when it was placed (which has a dropdown to view/select from all instances of the request being made), and the response (which has a WHOLE LOTTA options, itself. I won't be explaining all of those here, but please play around and see what different options/information are available).

Alright, we've made our first request! Now that we've done a GET request....

Step 4: Make a POST Request

I want to try logging in now. The docs say that I need a username and password in my request body in order to login. I'll use credentials that I know to be correct and stored in this API's database.

Make a New Request (I'll title mine "Login"). Here, I want to select POST for the request type and JSON for the body format.

Once you hit CREATE you'll need to complete the rest of the request. For Login, I need to add the URL/endpoint and the body. Once I complete all required fields for my request, I can hit SEND.

HECK YEAH!! Another successful request made. You'll see the body as it was sent on the left and the response on the right (or you can view with a top/bottom split). This response contains a very important piece of information, our JWT. For all endpoints following a login, the requests must contain an Authorization header with this JWT. Let's see how to make one of those.

Step 5: Make a Request that Requires a Header

Let's make another post request, to create some data. Only now, we must use our JWT to access the endpoint. Make a New Request and select the proper type & format. Then, complete the request URL/endpoint and body (make sure all required fields are included). Once you've done that, click on the HEADER tab. I want to make a header called Authorization and paste in the JWT I received from my Login request. Once I've done that, I'll hit SEND.

YES, successful requests never get old. 💚

Again, you can see the request body on the left, the response on the right, and the info bar up top. Getting the hang of this? Awesome.

Now that you're more familiar with Insomnia, I'll quickly show you how to make PUT and DELETE requests.

Step 6: Make a PUT Request

You know the drill. Make a request, select the proper options, complete the body, headers, etc., then SEND. For a PUT request, your body will include the property/properties that you want to update.

Step 7: Make a DELETE Request

Make request, select options, yadda yadda. Got it? Cool. With a DELETE request, you won't need a body. For my API I just need the Authorization header and to include the id for which item I want to delete in the endpoint param (for example, my URL ended up looking like this "https://tripsplit-backend.herokuapp.com/api/trips/7", 7 being the id).

Aaaaaand there you go. How to use Insomnia to test your endpoints and make HTTP requests.

I appreciate you taking the time to check this article out and I hope it helped you in some way. ❤️

DEV Community: Katie McKnight