Insomnia is an easy to use REST API client useful for designing and debugging API's.
There are many reasons to use Insomnia, these are our top 3:
- It has a graphical user interface that allows for quick testing of different routes and configs.
- A powerful templating system that allows for complex setups with different auth flows and easy chaining of requests.
- Ability to share workspaces with colleagues or teammates.
It's much easier to use than a web-browser or cURL, and can dramatically
increase your development velocity if you find yourself often working with
APIs - both developing and consuming.
In this guide we will use Insomnia to Authenticate to an API and make some
simple requests that will show you the benefit of using Insomnia over
cURL or a web-browser. Towards the end we will (optionally) look at setting
up the Insomnia workspace for the Dwyl smart-home-security-system
We will be using insomnia-core which is an API consuming tool. You still
have to design and build the API yourself, but you can use Insomnia to test
and consume your new API. API design itself it out of scope - if you want to
learn how to do this: https://github.com/dwyl/learn-api-design
In case you're wondering about the name of the product,
insomniais meant to be a play on "REST" ... as in REST API.
This guide is designed for people who have little to no experience in consuming APIs or want to know how to do so using Insomnia.
If you already have an excellent understanding of developing REST APIs, this guide probaly isn't for you.
The easiest way to do this is to install it from the official website:
https://insomnia.rest/download
Make sure you download and install Insomnia.
For this tutorial, we will be using an example rest server. Clone this repository,
git clone https://github.com/dwyl/learn-insomnia
We have included two example servers, functionally identical, but written in different styles/languages.
If you're familiar with Elixir and/or the MVC pattern,
use the server in elixir_server,
or if your familiar with go OR have little/no programming knowledge,
use the server in go_server.
If you're familiar with Elixir, there is a Phoenix server included in
elixir_server.
Presuming you have Elixir setup and installed, run this by:
mix deps.get
mix phx.server
In learn-insomnia you should find a folder called server, and within that
an executable called go_server, on mac run this using
./server
This will run a simple Todo-list REST server on port 4000.
If you want to double check the source code, it's in
main.go.
If you're curious about theGoprogramming language, see: https://github.com/dwyl/learn-go
When you first open Insomnia, you will see an empty workspace:
Create a new project by clicking the + icon button:
Name it "Todo List" or something similar:
A project in Insomnia is a collection of related routes and configuration. Within one project, there are several other ways of organising your routes:
-
Environments: Useful for global configuration changes: E.g. changing URLs from development to production or changing authentication state.
-
Folders: Pretty self explanatory, each folder can group routes together and can hold there own configuration.
Inside each project, you can have design documents and collections of requests.
Insomnia is an HTTP API client. To consume APIs, we must first create a route or URL.
Let's do that now.
Inside the project we just created,
click on the New Collection button.
Call it "Basic Requests" or something similar. We are ready to create a new request.
Click on New HTTP Request.
This will create a new request called "New Request".
If you double click it, you can rename it to "List Todos".
Once you've done that, a URL bar should appear at the top of the window, let's type in the URL of the local server you ran earlier:
http://localhost:4000/
Click "send", and you should get a response!
As we can see, Insomnia is made of three key parts:
-
Left Pane This contains all your routes and current Project and environments. You'll also see a
cookiesbutton, Insomnia keeps track of cookies as well! -
Middle Pane This contains request information. Take some time to investigate each of the tabs. We'll work on adding the
Bodyandauthsections later, but it's good to have an idea of how it all works. -
Right Pane This contains response information. Again, poke around! By default it shows the response body.
Let's create a new route to send data to the server - POST Request!
Create a new route, called "Create Todo".
Click on the + icon and click on HTTP Request.
This will prompt you to create a new request. Name it "Create Todo" by double clicking on the newly created request.
Click on the GET dropdown and change it to POST.
Once you've created the POST request,
you will need to enter some data,
in order to execute the request.
The URL is the same: http://localhost:4000/
You will need to send some data, e.g:
{ "item": "hello world"}Click on the Body dropdown, choose JSON
and paste the text.
If you click Send,
you should expect to see a 200 response from the server
confirming that your new todo item was created.
Manually inputting the URL for each new request is fine for two or three routes but once you get to 20+ it starts getting tedious. Then what happens if the URL changes or we want to access our production API? Do we need to go through and change every single URL?
Insomnia has great templating capability, so lets try it out to template in our URL!
Click the "No environment" dropdown, then "Manage Environments":
Then, press the "+" button next to sub environments. Create a public environment.
Double click the environment name ("New Environment") to edit it: Change it to something like "Development":
Lets add a host environment variable that we can use in our URL:
{"host": "http://localhost:4000"}
Once you've clicked "Close" to finish creating the "Development" environment
with the "host" variable, you will be taken back to the home view.
To use the development environment, you will need to select the "No Environment" drop down and click on "Use Development":
Let's go back to the requests and use our new template in the URL. Make sure your environment is not set to "Development" in the top left of the screen.
For both requests, change the URL bar to {{ host }}:
Our server accepts JSON data, so let's create a JSON request in Insomnia.
Go to the "Body" dropdown and select JSON.
Our todo list schema requires
us to specify an item field in our JSON,
so let's define our request now.
Type this out in the Body:
{
"item": "Review PR"
}Click "Send",
the server should respond with the complete body,
with the addition of an id assigned to the item:
Once APIs get complicated and large enough, most common tasks involve multiple requests and passing arguments and results from one request to the next. This can get tedious when requests have to be made multiple times, or involve lots of different parameters.
Luckily, Insomnia has our back here too. We can use results from old requests in our new ones. Let's do this now.
Create a new get request called "View Item":
In the URL bar, set the url to {{ host }} like we did before.
Add a slash afterwards ({{ host }}/todo/)
so the URL will be expanded to something like:
http://localhost:4000/todo/.
Press Shift + Space to bring up the autocomplete menu.
Scroll down to find response => body attribute and select it.
This is a template tag
and these are effectively functions that we can use to transform data
from different parts of our app.
Insomnia shows this tag has an error:
This is because we haven't pointed it at any data yet. so lets do this now
Click on the tag to edit it.
First, we need to select what request we want to pull data from.
In this case, we want to use the ID of the item we just created,
so select POST Add Todo.
Then, we need to select the specific bit of data we want from that response. Insomnia supports JSONPath - A JSON query language - so lets use that to pick out the ID:
In Filter, write:
$.id
$ is our base response, and where selecting the id value
Your Tag should look like this:
Press done, then 'Send'. You should get a response containing the Todo you just created!
Obviously this is a simple example, but very quickly you can put together very powerful request chains that transform lots of data throughout your app. You can also combine these tags with the environment variables we specified earlier to make re-useable tags.
Most APIs require some form of authentication to access. Insomnia has support for many different types of authentication. We won't go into exploring all of these but we'll walk-through a quick example of using a bearer token to authenticate.
Open up the environment editor again by going
Development -> Manage Environments, and add another variable called "Token".
Set this to "hunter2":
Create a new GET request called "View Admin Page" and set the URL to
{{ host }}/admin:
Go to the auth tab and select "Bearer token". This sets the Authorization
header in the request. Go ahead and set that to our template, {{ token }}.
Ignore the prefix for now.
Press send and you should get a "Successfully Authenticated!" Response!
The beauty of the template system is that you could change your environment in future to "Production", declare your production values and then use your production servers without having to change any of the individual requests!
Insomnia offers many features, including designing and debugging the API. It is crucial we thoroughly test an API before pushing it to production.
Let's create a Test Suite inside Insomnia. In the same project as before,
click on the + Create button
and select Design Document.
A design document holds specifications, API requests and tests. We can sync design documents with Git.
For more information, check https://docs.insomnia.rest/insomnia/get-started-with-documents.
After naming the file to whatever you want,
paste the code of the open_api_specs.yaml file.
This file has the Open API Specification details of the API being used.
On top of the file, click on the Test button.
You will be prompted to create a new Test Suite.
After clicking this button and naming your suite (we named ours "Basic Suite").
Now click on the Debug button.
You will see it is empty.
Create the same requests we made earlier
(list items, get specific item, create item).
After this, you should have a screen similar to this.
When creating a design document,
we need to create the requests within it
so they are accessible in the Test tab.
Inside the Test tab,
click on the New Test button.
A modal will appear to create a new one.
Name it "Returns 200".
Click on the -- Create Request -- button,
and choose the List Items option.
If you click on Run Tests,
the test should pass.
As time of writing, you can only implement unit tests. For stress testing, you have to resort to other options.
Additionally, even though you can make manual changes to the unit test, you can't dynamically change according to the environment.
This poses some limitations, as you can't tinker with variables for success and fail scenarios.
These features are to be implemented, though. Check the following issues for more options:
You can use Insomnia to run the Test Suites you've created within a CI pipeline.
In Github, you're most likely going to be using Github Actions.
Luckily, Insomnia offers a CLI
that we can use whilst executing our CI pipelines.
To quickly get it working,
we need to follow a few steps to run our Test Suite.
Inside the design document,
click on it and select the Import/Export option
Click on Export Data
and choose the first option.
Select all the requests we've implemented.
This will create a JSON file
that Insomnia CLI can use to run the tests.
You can place this in the root of your project
and rename it to insomnia.json.
To create our Github Action workflow .yml file,
we can make use of the Setup Inso action
to install the CLI.
Create a file called test.yml inside .github/workflows
and add the follow code.
name: Test
on:
push:
branches: [ "master" ]
pull_request:
branches: [ "master" ]
jobs:
Linux:
name: Validate API spec
runs-on: ubuntu-latest
steps:
- name: Checkout branch
uses: actions/checkout@v1
- uses: kong/setup-inso@v1
with:
inso-version: 3.5.0
- name: Lint
run: inso lint spec "my-spec.yaml" --ci --src insomnia.json
- name: Run test suites
run: inso run test "my-spec.yaml" --ci --env "Test Env" --src insomnia.jsonWhen running test suites,
we are running the inso run test
command.
We are stating we want to run the my-spec.yaml design document,
inside the "Test Env" environment that was created for testing purposes.
We are telling the CI to look for the insomnia.json file we created earlier.
Take note that, if you are following the previous steps, your requests are pointing to
localhost:4000. The CI will fail because nothing will be running onlocalhostinside the CI environment. Make sure the URL domain is accessible from Github Actions.In this repo's case, we are using
phoenix-todo-list-tutorial's API.