Setup: Install Insomnia

Install Insomnia on your Mac, 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 a Mac 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 brew install --cask 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.

macOS 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 macOS and Windows.

Install Insomnia

In the Terminal, run:

brew install --cask insomnia

--cask tells Homebrew this is an app with a window, which goes in your Applications folder, rather than a command-line tool.

Make your free account

Open Insomnia from your Applications folder (or press Command+Space and type Insomnia). If macOS asks whether you're sure you want to open an app downloaded from the internet, click Open. 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.

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. Quit Insomnia with Command+Q, 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
Error: It seems there is already an App at '/Applications/Insomnia.app' Insomnia was installed earlier from a download. Drag it from Applications to the Trash, then run the install command again.
macOS says Insomnia can't be opened Open System Settings > Privacy & Security, scroll down, and click Open Anyway next to Insomnia.
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