Lesson 23 · Advanced .NET

Building a web API with ASP.NET Core

A web API is a program that answers HTTP requests from other programs with data, usually JSON. Build a whole to-do API in nine lines of C# with ASP.NET Core minimal APIs, then follow real requests through it: Kestrel reads the request, routing picks the endpoint by method and path, System.Text.Json turns the body into a Todo, the handler adds it to a list, and the result goes back as 201 Created, 200 OK, 405 or 404.

14 min12 steps5 questionsAdvanced

Fig 23 · Interactive

Loading figure…

or ← →

Check yourself

5 quick questions

Pick an answer to see why. Your score saves with your progress.

01What does app.MapPost("/todos", (Todo t) => { ... }) do when that line runs?

MapPost only registers an endpoint (method + route pattern + handler). Nothing runs until a matching request arrives after app.Run() starts Kestrel.

02The client sends POST /todos with the body {"id":1,"title":"Buy milk"}. How does the handler get a Todo t?

Because t is a complex type, minimal APIs bind it from the JSON body. The web defaults match property names case-insensitively, so "title" fills Title.

03What does Results.Created($"/todos/{t.Id}", t) send back?

201 Created says a new resource was made; the Location header says where it lives, and the value is written as JSON in the body.

04GET /todos returns a List<Todo> holding Todo(1, "Buy milk"). What is the response body?

ASP.NET Core serializes the result with System.Text.Json web defaults, which use camelCase property names, with status 200 OK and a JSON content type.

05The API has only GET /todos and POST /todos. What does DELETE /todos get?

The path matches endpoints, but none for DELETE, so routing answers 405 Method Not Allowed (with Allow: GET, POST). A path with no endpoint at all, such as /nope, gets 404.

Key terms

Glossary

Web API: A program that answers HTTP requests from other programs with data, usually JSON, instead of web pages.
ASP.NET Core: The .NET framework for building web apps and web APIs; minimal APIs are its shortest way to write endpoints.
Kestrel: The web server built into ASP.NET Core. It listens on a port and turns bytes into HTTP requests.
Endpoint: An HTTP method plus a route pattern, linked to a handler, such as GET /todos → () => todos.
Routing: Matching each request's method and path to an endpoint. A path with no endpoint gets 404; a wrong method gets 405.
Parameter binding: Filling a handler's parameters from the request: here, reading the JSON body into a Todo.
Status code: The three-digit result of a response: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 405 Method Not Allowed.
JSON: A text format for data, such as {"id":1,"title":"Buy milk"}; System.Text.Json converts it to and from C# objects.

Fine print

Notes and sources

The list lives only in the server's memory: stop the app and the to-dos are gone. A real API keeps them in a database, for example with Entity Framework Core.
Kestrel can handle many requests at the same time on different threads, and List<T> is not safe for that. Real code uses a database, a lock or a thread-safe collection such as ConcurrentDictionary.
Here the client chooses the Id to keep the code short. A real API usually lets the server or the database choose it.
The HTTP messages in the figure show only the headers that matter here. Real responses also carry Date, Server and Content-Length or Transfer-Encoding.
When no URL is configured, Kestrel listens on http://localhost:5000. A plain dotnet run on a dotnet new web project uses Properties/launchSettings.json instead: the template wrote a port there once, when it made the project, so it is not 5000. dotnet run --no-launch-profile skips that file. Or copy the address from the "Now listening on:" line.
Handlers can also be async: a lambda that returns Task<T> lets the thread serve other requests while it waits for a database or another service.
The program is real C#. Put the nine lines in Program.cs of a dotnet new web project, start it with dotnet run --no-launch-profile, then try: curl -i -X POST http://localhost:5000/todos -H "Content-Type: application/json" -d '{"id":1,"title":"Buy milk"}'

Quiz Unlocks after the last step.