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.

Key terms

Cheat sheets