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

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

Cheat sheets