Insomnia: GET
Before you write the GET method, save the request you want it to answer in an Insomnia collection, with your API's address in an environment, send it, and read what comes back.
Journeyman · Spring Boot · REST API · Updated
After this lesson you can
- Save requests for a Spring Boot API in an Insomnia collection, with its address in an environment variable
- Read a Spring Boot API'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.
Creating a REST Controller showed the whole CategoriesController. Now you build it, one method at a time, starting with a class that has its constructor and no methods yet. Before you write the first method, 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
A Spring Boot app runs at http://localhost:8080, unless server.port in application.properties sets another port. You'll type that address in every request, and it can change: a classmate's API may use another port, and an API on a server has 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:8080 |
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 you want
Add an HTTP request to the collection, name it All categories, and set it to:
GET {{ _.base_url }}/api/categories
Run your Spring Boot app in IntelliJ, and click Send in Insomnia. The answer is 404 Not Found, in orange: your controller has no method for that address yet. Spring Boot sends a small JSON body that says so:
{
"status": 404,
"error": "Not Found",
"path": "/api/categories"
}
(It also has a timestamp: the date and time of the error.) That's expected. It's the first item on your to-do list.
Reading an answer
An answer has three parts, and Insomnia shows each one:
| Part | Where Insomnia shows it | In the answer you want |
|---|---|---|
| Status code | At the top of the answer, in color | 200 OK, in green: it worked |
| Headers | The Headers tab | Content-Type: application/json: the body is JSON |
| Body | The Preview tab, under the status | A JSON array of every category, starting with Beverages and Condiments |
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.
Here is the start of the body you want once the next lesson is done:
[
{
"categoryId": 1,
"categoryName": "Beverages",
"description": "Soft drinks, coffees, teas, beers, and ales"
},
{
"categoryId": 2,
"categoryName": "Condiments",
"description": "Sweet and savory sauces, relishes, spreads, and seasonings"
},
...
]
A green 200 OK isn't enough on its own: if the body were an empty list, [], the status would still be 200, and the answer would still be wrong. Check the body too.
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 write the method, if it's next on your list |
Error: Couldn't connect to server |
Nothing is running at base_url |
Run the app in IntelliJ, or check the port in base_url |
Check yourself
2 questions to try on the lesson page.
So what
Your collection now holds the API's first to-do item. In the next lesson you write the GET method, then send All categories again until it answers exactly what you wrote down.