Setup: Install Insomnia

Install Insomnia, the app you use to send requests to web APIs and read their answers, make a free account with a project stored on your computer, and send your first request.

Novice · Operating System · REST API · Updated

After this lesson you can

  • Install Insomnia on Windows and send a saved GET request from a collection

Key takeaways

  • An API client sends a request to a web address and shows the whole answer, status code and all. Insomnia is the API client this course uses.
  • Install it with winget install -e --id Insomnia.Insomnia.
  • A free account with a Local Vault project keeps every request you save on your own computer.
  • A collection is a folder of saved requests. Click one and press Send to ask again, any time.
  • 200 OK at the top of the answer means the server found what you asked for.

Windows only. Later in this course you build web APIs: programs that answer requests with data instead of web pages. While you build one, you need to ask it questions and see exactly what it answers.

Your web browser can ask a web address for something, but only in one way: it can get a page. It can't send new data, change data or delete it, and it hides most of the answer. An API client is an app built for this job. You type the address, choose what kind of request to send, press Send, and see the whole answer. This course uses the API client Insomnia, version 13. It's free, and it works the same way on Windows and macOS.

Installing Insomnia

Watch the video on YouTube

Install Insomnia

In Git Bash, run:

winget install -e --id Insomnia.Insomnia

Click Yes if Windows asks whether the app may make changes. Watch the id: Insomnia.Insomnia is the API client. There is an unrelated app that keeps your computer awake with a similar name, which is why -e matters.

Make your free account

Open Insomnia from the Start menu. The first screen asks you to sign in.

  1. Choose to create an account, and sign up with your email address or your GitHub account. The account is free.
  2. Don't choose Use the local Scratch Pad at the bottom of that screen. The course keeps your requests in a project, so you can bring in the requests that come with the exercises later.
  3. If Insomnia offers a paid plan, keep the free one.

Make a project that stays on your computer

A project holds your work in Insomnia. Where it keeps that work is up to you:

Storage Where your requests are kept
Local Vault Only on your computer
Cloud Sync On Insomnia's servers, so you can see them on other computers
Git Sync In a Git repository

Choose Local Vault. Requests you send to your own APIs never need to leave your computer.

  1. In the left sidebar, click the + next to Projects.
  2. Name the project Bootcamp, choose Local Vault, and click Create.

Make a collection and send a request

A collection is a folder of saved requests, like a playlist: you build each request once, then click it and send it again whenever you want.

  1. In your Bootcamp project, click Create, then API Collection. Name it First requests.
  2. Click the + in the collection's sidebar, choose HTTP Request, and name it Glossary categories.
  3. Leave the method, on the left of the address bar, set to GET.
  4. In the address bar, type this address, then click Send:
https://www.ask-codey.com/api/glossary/categories

This is a real web API: the one that runs this site's glossary. You just asked it for its list of categories.

Insomnia after sending GET https://www.ask-codey.com/api/glossary/categories: 200 OK at the top of the answer, and a JSON list whose first category is General

Read the answer

The answer appears on the right:

  • The status code, at the top: 200 OK, in green. It means the server found what you asked for. You'll meet the other status codes when you build an API of your own.
  • How long it took and how big it was, next to the status code.
  • The body, under it: the data itself, written as JSON, a list in square brackets of categories in curly braces. The first one starts like this:
{
  "name": "General",
  "slug": "general",

Insomnia saves the request as you go. There's no save button to remember.

Check your work

  1. Close Insomnia, then open it again.
  2. Open your Bootcamp project and your First requests collection. Glossary categories is still there.
  3. Click it and click Send. You see 200 OK again.

Common problems

What you see What to do
winget installs an app called Insomnia that only keeps your computer awake The id was wrong. Uninstall that app from Settings > Apps > Installed apps, then run the install command again, -e and all.
Error: Couldn't resolve host name The address is mistyped, or you aren't connected to the internet. Check every letter of www.ask-codey.com.
404 Not Found The server is fine, but nothing lives at that address. Check the part after .com: /api/glossary/categories.
The project has no Local Vault choice You're working in the Scratch Pad. Sign in with your account first, then make the project.
Your requests are gone after you reopen Insomnia You signed in with a different account, or worked in the Scratch Pad. Sign in with the account you made the project with.

Check yourself

2 questions to try on the lesson page.

So what

From here on, every web API you build gets its own collection in Insomnia. You'll write the request first, see what the API answers, and send it again after every change, until it answers exactly what you want.

Key terms

Cheat sheets