Insomnia: POST

Before you build the POST action, write the requests that add a category in Insomnia, each with a JSON body, send them, and learn why the answer today is 405 Method Not Allowed instead of 404.

Journeyman · REST API · ASP.NET Core · Updated

After this lesson you can

  • Send a POST request with a JSON body from Insomnia
  • Tell 405 Method Not Allowed from 404 Not Found

Key takeaways

  • A POST sends data in a body. In Insomnia, choose JSON on the Body tab and type the new item; Insomnia adds the Content-Type header for you.
  • 405 Method Not Allowed means the address exists, but nothing there answers that method. 404 Not Found means nothing answers at the address at all.
  • The answer you want from a POST is 201 Created, the saved item with its new id, and a Location header with its address.
  • Every successful send of a POST adds another item, so expect a new id each time.

Your API can read categories. Next it will add them. As before, start by writing down what you want it to answer, as requests in your Northwind API collection.

A GET asks for something. A POST brings something: the new category, in the request's body. Think of it as the difference between asking a shop what's on the shelf and handing over a box to put on it.

A request with a body

In Insomnia, add a request to the Northwind API collection, name it Add Snacks, and set it to:

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

Then give it a body:

  1. Open the Body tab, under the address bar, and choose JSON.
  2. Type the new category:
{
  "categoryName": "Snacks",
  "description": "Chips, nuts and pretzels"
}

Choosing JSON also adds a header to the request, Content-Type: application/json, which tells the API what kind of body is coming. Open the Headers tab to see it. You don't type it yourself.

There's no categoryId in the body. The database chooses the new id, so the client doesn't send one.

405, not 404

Start your API, and send Add Snacks. The answer is 405 Method Not Allowed.

Why not 404 Not Found, as Category 8 answered before you built it? Because the address isn't the problem. /api/categories exists: your All categories request gets an answer from it. What's missing is an action that answers POST there.

Status Means
404 Not Found Nothing answers at this address, whatever the method
405 Method Not Allowed Something answers at this address, but not to this method

The answer's Headers tab shows which methods the address does accept: Allow: GET.

The answer you want

Once the next lesson is built, Add Snacks should answer 201 Created, which means "saved, and here it is". Three things to check:

  • The status: 201 Created.
  • The headers: a Location header with the new category's address, such as http://localhost:5179/api/categories/9.
  • The body: the saved category, now with the id the database gave it:
{
  "categoryId": 9,
  "categoryName": "Snacks",
  "description": "Chips, nuts and pretzels"
}

Each successful send adds another Snacks, with a new id: 9, then 10, then 11. That's what a POST does. If you send it a few times while you test, the extras are harmless in your own database.

A request that should be turned away

Add one more request, Add a bad category, the same method and address, with a name longer than the 15 characters the table allows:

{
  "categoryName": "A name that is far too long",
  "description": "Too long"
}

Today it answers 405, like Add Snacks. The answer you want is 400 Bad Request, with a body that names the field that's wrong, CategoryName. An API should refuse bad data with a clear reason, not save it, and not crash.

Do it: tell 404 from 405

Before you build an action, its request in Insomnia answers 404 Not Found or 405 Method Not Allowed, and the difference tells you what's missing. Write a method that works out which, from the list of what the API answers today.

The method gets three values:

  • endpoints: what the API answers today, a List<string>. Each one is a method, a space, and an address, such as "GET /api/categories".
  • method: the request's method, a string, such as "POST".
  • address: the request's address, a string, such as "/api/categories".

For example, after GET, the API answers two endpoints, and you send Add Snacks, a POST to /api/categories:

List<string> endpoints = new List<string> { "GET /api/categories", "GET /api/categories/8" };
Question For POST /api/categories
Does an endpoint have this method and this address? no
Does an endpoint have this address, with another method? yes: GET /api/categories
The answer "405 Method Not Allowed"

So Check(endpoints, "POST", "/api/categories") returns "405 Method Not Allowed".

Your job: write the method Check(List<string> endpoints, string method, string address) so it returns a string.

  • When an endpoint has this method and this address, return "an action answers".
  • Otherwise, when an endpoint has this address with another method, return "405 Method Not Allowed".
  • Otherwise, return "404 Not Found": nothing answers at this address.

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

Two new to-do items in your collection: one that should be saved, and one that should be refused. In the next lesson you build the POST action, and send both again until Add Snacks answers 201 Created and Add a bad category answers 400.

Key terms

Cheat sheets