# Web APIs with Controllers: an overview

REST is the common way to design a web API. Each kind of data is a resource with its own address, and the HTTP method says what to do with it. GET, POST, PUT and DELETE match SELECT, INSERT, UPDATE and DELETE, each with its usual status code.

Apprentice · REST API · ASP.NET Core · Updated November 3, 2026

## After this lesson you can

- Match each REST method and address to a CRUD operation and its usual status code

## Key takeaways

- In REST, each resource has its own address: `/api/categories` for the collection and `/api/categories/8` for one item.
- Addresses name things, never actions. The HTTP method says what to do.
- `GET` reads (`200`), `POST` creates (`201`), `PUT` replaces (`200`) and `DELETE` removes (`204`), like `SELECT`, `INSERT`, `UPDATE` and `DELETE`.
- Data travels as JSON both ways, and ASP.NET Core converts between JSON and your C# objects.
- Minimal APIs suit small APIs with a few endpoints; controllers suit larger ones, with one class per resource.

The to-do API in the last lesson followed a pattern: one address for the list, one for each item, and a different HTTP method for each thing you could do. That pattern has a name: **REST** (*Representational State Transfer*), a set of rules for web APIs written down in 2000 and used by almost every API since.

## Resources and addresses

In REST, each kind of data is a **resource** with its own address:

- `/api/categories` is the **collection**: all the categories.
- `/api/categories/8` is **one item** in it: category 8.

Addresses name **things**, never actions. There's no `/api/getCategory` or `/api/deleteCategory`; what to do is said by the method.

## Methods are CRUD

The four main HTTP methods match the four things you do with data, and the four SQL statements you already know:

| Method | Address | Does | Like SQL's | Usual success code |
|---|---|---|---|---|
| `GET` | `/api/categories` | Read all of them | `SELECT` | `200 OK` |
| `GET` | `/api/categories/8` | Read one | `SELECT ... WHERE` | `200 OK` (or `404 Not Found`) |
| `POST` | `/api/categories` | Create a new one, from the body | `INSERT` | `201 Created` |
| `PUT` | `/api/categories/8` | Replace one, from the body | `UPDATE` | `200 OK` (or `404`) |
| `DELETE` | `/api/categories/8` | Delete one | `DELETE` | `204 No Content` (or `404`) |

Create, read, update and delete are known together as **CRUD**. A `POST` and a `PUT` both answer with the item as it was saved, and a `DELETE` answers with no body, because the item is gone. Learn this table, and you can guess how almost any REST API works before reading its documentation.

## JSON in, JSON out

Data travels as **JSON** in both directions: a `GET` answers with JSON in the response body, and a `POST` or `PUT` sends JSON in the request body. ASP.NET Core turns your C# objects into JSON, and JSON back into objects, without you writing any of it.

## Minimal APIs or controllers?

You've seen a minimal API: lambdas mapped in `Program.cs`. The other way is **controllers**: classes with one method per endpoint, just like MVC's controllers, but answering with data instead of views.

| | Minimal API | Controllers |
|---|---|---|
| Endpoints are | Lambdas in `Program.cs` (or grouped in extension methods) | Methods in controller classes |
| Good for | Small APIs, a few endpoints, quick services | Larger APIs, many endpoints grouped by resource |
| Feels like | A script | MVC, which you already know |

Both are fully supported, and both run on the same ASP.NET Core underneath. The rest of this topic builds a categories API for Northwind with **controllers**, so each resource gets one tidy class.

## Check yourself

1 question to try on the lesson page.

## So what

REST turns API design into a pattern: a noun for the address, a method for the action, a status code for the result. Follow it, and anyone who knows REST can use your API almost without instructions.

## Key terms

- [REST](https://www.ask-codey.com/glossary/rest)
- [Resource](https://www.ask-codey.com/glossary/resource-rest-api)
- [CRUD](https://www.ask-codey.com/glossary/crud)
- [JSON](https://www.ask-codey.com/glossary/json)

## Cheat sheets

- [Web APIs with Controllers: an overview](https://www.ask-codey.com/cheat-sheets/web-apis-with-controllers-an-overview-cheat-sheet)

Source: https://www.ask-codey.com/lessons/web-apis-with-controllers-an-overview