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, anint. It's always200or404.body: the answer's body, astring.wantedBody: the body you wrote down as the answer you want, astring.
(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
200and the body is exactly the wanted body, return"done". - When the status is
200and 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.