Insomnia: GET

Before you build the next GET actions, write the requests you want them to answer in an Insomnia collection, with your API's address in an environment, send them, and read what comes back.

Journeyman · REST API · ASP.NET Core · Updated

After this lesson you can

  • Save requests in an Insomnia collection, with the API's address in an environment variable
  • Read a response's status code, headers and body in Insomnia

Key takeaways

  • Write the request before the code. A request that answers 404 Not Found today is a to-do list item; when it answers what you want, the item is done.
  • A collection holds your API's requests. Its environment holds base_url, and every request starts with {{ _.base_url }}, so a new address is one change.
  • Read the status code first, then the headers, then the body.
  • 200 OK with the wrong data is still wrong. Compare the body with the answer you want, not just the status.

Your categories API answers one request: GET /api/categories, all eight categories. Next you'll teach it two more: one category by its id, and a search. Before you write that code, write down what you want it to answer.

A request in Insomnia makes a good to-do item. Send it now, and it fails, because the code isn't there yet. Write the code, send the same request again, and when the answer is the one you wanted, the item is done. You saw the same idea with unit tests: a test that fails first, then passes.

A collection for your API

Open Insomnia, then your Bootcamp project from Setup: Install Insomnia. Click Create, then API Collection, and name it Northwind API. Every request you send this API goes in this collection.

One address for every request

Your API runs at an address such as http://localhost:5179. Yours may have a different number: it's the http profile's applicationUrl in Properties/launchSettings.json. You'll type it in every request, and it will change: later in the course the same API runs on Azure, at a new address. So write it once, in an environment.

An environment is a list of named values for a collection. In the Northwind API collection, open its environment (Base Environment), and add one value:

Name Value
base_url http://localhost:5179

Now any request can start with {{ _.base_url }}. Insomnia puts the address in when it sends, and shows it as a colored tag in the address bar. When the address changes, you change one value, and every request follows.

The request that already works

Start your API with Ctrl+F5. In Insomnia, add an HTTP request to the collection, name it All categories, and set it to:

GET {{ _.base_url }}/api/categories

Click Send. The answer has three parts, and Insomnia shows each one:

Part Where Insomnia shows it Here
Status code At the top of the answer, in color 200 OK, in green: it worked
Headers The Headers tab Content-Type: application/json; charset=utf-8: the body is JSON
Body The Preview tab, under the status The data itself: a JSON array of all eight categories

Read them in that order. The status says whether it worked, the headers say what kind of body came back, and the body is the data. The Timeline tab shows the whole conversation as text, request and answer, exactly as it went over the network:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[{"categoryId":1,"categoryName":"Beverages","description":"Soft drinks, coffees, teas, beers, and ales"}, ...]

The requests you want next

Add two more requests to the collection.

Category 8, one category by its id:

GET {{ _.base_url }}/api/categories/8

Send it. The answer is 404 Not Found, in orange: nothing in your API answers that address yet. That's expected. Here is the answer you want once the next lesson is done, 200 OK with this body:

{
  "categoryId": 8,
  "categoryName": "Seafood",
  "description": "Seaweed and fish"
}

Search categories, a search for the names that contain pro:

GET {{ _.base_url }}/api/categories?search=pro

Send it. This time the status is 200 OK, but read the body: it's all eight categories again. Your API ignores ?search=pro, because nothing asks for it yet. A green status doesn't mean the answer is right; the body has to match too. The answer you want is a list of two categories, Dairy Products and Produce.

What a status code tells you

Status Means What to do
200 OK It worked, and the body holds the answer Check the body is the data you wanted
404 Not Found Nothing answers at this address Check the address; or build the action, if it's next on your list
Error: Couldn't connect to server Nothing is running at base_url Start the API, or check the port in base_url

HTTP Status Codes: an overview, earlier in this chapter, covers the rest.

Do it: tell a finished request from one still to do

Your Northwind API collection is a to-do list: a request is done when it gets the answer you wrote down. Write a method that reads one answer and says where that request stands.

The method gets three values:

  • status: the answer's status code, an int. It's always 200 or 404.
  • body: the answer's body, a string.
  • wantedBody: the body you wrote down as the answer you want, a string.

(Real bodies are JSON. Here they're short text, so they're quick to read.)

For example, Search categories today: the status is a green 200, but the body is all eight categories, not the two you want.

Value Here
status 200
body "Beverages, Condiments, Confections, Dairy Products, Grains/Cereals, Meat/Poultry, Produce, Seafood"
wantedBody "Dairy Products, Produce"
Where it stands a 200, but not the body you want: "wrong data"

So for these values, RequestState(status, body, wantedBody) returns "wrong data".

Your job: write the method RequestState(int status, string body, string wantedBody) so it returns where the request stands, a string.

  • When the status is 404, return "not built yet", whatever the body is.
  • When the status is 200 and the body is exactly the wanted body, return "done".
  • When the status is 200 and the body is anything else, return "wrong data".

Practiced live on the lesson page: write the C# right there and check it.

Check yourself

2 questions to try on the lesson page.

So what

Your collection is now the API's to-do list: one request done, two waiting. In the next lesson you build the GET actions, then send Category 8 and Search categories again until they answer exactly what you wrote down.

Key terms

Cheat sheets