# Your First Minimal API

A minimal API maps each address and method straight to a lambda in Program.cs, with MapGet, MapPost, MapPut and MapDelete. The lambda's parameters come from the route and the body, and Results.NotFound(), Results.Created() and friends choose the status code.

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

By Gregor Dzierzon

## After this lesson you can

- Map GET, POST, PUT and DELETE endpoints to lambdas in a minimal API
- Return a status code with Results, such as Results.NotFound() or Results.Created()

## Key takeaways

- A minimal API maps each method and address to a lambda in `Program.cs` with `MapGet`, `MapPost`, `MapPut` or `MapDelete`.
- A parameter such as `int id` gets its value from `{id}` in the address; a class parameter such as `Todo todo` comes from the JSON body.
- Return an object or a list, and it's sent as JSON with `200 OK`.
- Return a `Results` method, such as `Results.NotFound()`, `Results.Created(...)` or `Results.NoContent()`, to answer with a different status code.
- ASP.NET Core writes JSON property names in camelCase, so `Title` becomes `title`.

A **Web API** is a web app that answers with **data** instead of pages. A browser asks an MVC app for `/products` and gets back HTML to show. A program asks an API for `/api/products` and gets back JSON to use. Mobile apps, JavaScript in web pages, and other servers are all clients of APIs.

ASP.NET Core has two ways to build one. This lesson shows the smallest: a **minimal API**.

## Creating the project

In Visual Studio, create a new project from the **ASP.NET Core Web API** template, and on the last page **clear** the **Use controllers** box. (In a terminal: `dotnet new webapi -o TodoApi`.) The template's `Program.cs` holds a sample weather forecast; replace it with the to-do list below.

## A to-do list API

Here's a whole API in `Program.cs`: a to-do list kept in memory, with an endpoint for each thing a client can do.

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

// The to-do list, kept in memory: it starts again whenever the app restarts.
List<Todo> todos = new List<Todo>
{
    new Todo { Id = 1, Title = "Buy milk", Done = false },
    new Todo { Id = 2, Title = "Call the dentist", Done = true }
};

app.MapGet("/todos", () => todos);

app.MapGet("/todos/{id}", (int id) =>
{
    Todo? todo = todos.Find(t => t.Id == id);
    if (todo == null)
    {
        return Results.NotFound();
    }
    return Results.Ok(todo);
});

app.MapPost("/todos", (Todo todo) =>
{
    todo.Id = todos.Count == 0 ? 1 : todos.Max(t => t.Id) + 1;
    todos.Add(todo);
    return Results.Created($"/todos/{todo.Id}", todo);
});

app.MapPut("/todos/{id}", (int id, Todo changed) =>
{
    Todo? todo = todos.Find(t => t.Id == id);
    if (todo == null)
    {
        return Results.NotFound();
    }
    todo.Title = changed.Title;
    todo.Done = changed.Done;
    return Results.Ok(todo);
});

app.MapDelete("/todos/{id}", (int id) =>
{
    int removed = todos.RemoveAll(t => t.Id == id);
    return removed == 0 ? Results.NotFound() : Results.NoContent();
});

app.Run();

public class Todo
{
    public int Id { get; set; }
    public string Title { get; set; } = "";
    public bool Done { get; set; }
}
```

## Endpoints

Each `Map...` call creates an **endpoint**: a method and an address, joined to the code that answers it.

| Call | Answers |
|---|---|
| `app.MapGet("/todos", ...)` | `GET /todos` |
| `app.MapGet("/todos/{id}", ...)` | `GET /todos/2`, `GET /todos/7`, … |
| `app.MapPost("/todos", ...)` | `POST /todos` |
| `app.MapPut("/todos/{id}", ...)` | `PUT /todos/2` |
| `app.MapDelete("/todos/{id}", ...)` | `DELETE /todos/2` |

The code that answers is a **lambda**, like the ones you gave to LINQ. ASP.NET Core fills in its parameters for you:

- **`int id`** comes from the `{id}` in the address, converted to an `int`: `/todos/2` gives `id = 2`.
- **`Todo todo`** comes from the request's JSON body, turned into a `Todo` object. That's called **model binding**, as in MVC.

Whatever the lambda returns becomes the response. Return a list or an object, as the first `MapGet` does, and it's sent as JSON with `200 OK`.

## Choosing the status code with Results

When `200 OK` isn't the right answer, return one of the **`Results`** methods instead:

| Return | Answers |
|---|---|
| `Results.Ok(todo)` | `200 OK`, with the to-do as JSON, as the `MapPut` answers with the changed to-do |
| `Results.Created("/todos/3", todo)` | `201 Created`, with a `Location` header and the new to-do |
| `Results.NoContent()` | `204 No Content`: done, with nothing to send back, as after a `DELETE` |
| `Results.NotFound()` | `404 Not Found` |
| `Results.BadRequest("Give the to-do a title")` | `400 Bad Request`, with a message |

## Trying it

Run the app with **Ctrl+F5**, and send it two requests from Insomnia, the API client from *Setup: Install Insomnia*. In your `Bootcamp` project, make a collection named `Todo API`, and add two HTTP requests to it. Use your project's own address: it's the `http` profile's `applicationUrl` in `Properties/launchSettings.json`.

**`To-do 9`**, method **GET**:

```text
GET http://localhost:5248/todos/9
```

**`Add a to-do`**, method **POST**. This one carries the new to-do in its **body**: open the **Body** tab, choose **JSON**, and type it in.

```text
POST http://localhost:5248/todos
```

```json
{
  "title": "Water the plants",
  "done": false
}
```

Click **Send** on each one. The first answers `404 Not Found`: there's no to-do 9. The second answers `201 Created`. Insomnia shows the status at the top of the answer, the headers on its **Headers** tab, and the body below; its **Timeline** tab shows the whole answer as text:

```http
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /todos/3

{
  "id": 3,
  "title": "Water the plants",
  "done": false
}
```

JSON property names start with a small letter (`title`, `done`): ASP.NET Core converts C#'s `Title` to the *camelCase* that JavaScript clients expect, and back again when it reads a body.

Stop the app and start it again, and the new to-do is gone: the list only lives in memory. Real APIs keep their data in a database, as the next topic's do.

## Do it: add a to-do, or turn it away

The to-do API's `MapPost` adds every to-do it gets, even one with no title. Make it choosier: a to-do with an empty title is turned away with `400 Bad Request`, as `Results.BadRequest("Give the to-do a title")` answers, and isn't added. Write that work as a method, without the web part around it.

The method gets two values:

- `todos`: the to-do list, a `List<Todo>`. Each `Todo` has an `Id`, a `Title` and `Done`.
- `todo`: the new to-do from the request's body, a `Todo`. It has a `Title`, but no id yet: its `Id` is `0`.

For example, the list holds to-dos 1, 2 and 5 (3 and 4 were deleted), and a client adds *Water the plants*:

| Step | Here |
|---|---|
| Is the `Title` empty? | no: it's `"Water the plants"` |
| The highest `Id` in the list | `5` |
| The new to-do's `Id`: one more | `6` |
| Add it to the list | the list now holds 4 to-dos |
| The answer | `201` |

So `Add(todos, new Todo { Title = "Water the plants" })` returns `201`, and the new to-do's `Id` is `6`.

**Your job:** write the method `Add(List<Todo> todos, Todo todo)` so it returns the status code, an `int`.

- When the to-do's `Title` is empty (`""`), return `400`, and don't add it.
- Otherwise, set its `Id` to one more than the highest `Id` in the list.
- When the list is empty, set its `Id` to `1`.
- Add it to the list, and return `201`.

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

A minimal API is an address, a method and a lambda, repeated for each thing a client can do. It's the quickest way to put data on the web, and the same ideas, endpoints, model binding and status codes, carry straight over to controllers.

## Key terms

- [Web API](https://www.ask-codey.com/glossary/web-api)
- [Minimal API](https://www.ask-codey.com/glossary/minimal-api)
- [Endpoint](https://www.ask-codey.com/glossary/endpoint-rest-api)
- [MapGet and MapPost](https://www.ask-codey.com/glossary/mapget-and-mappost)
- [Results and TypedResults](https://www.ask-codey.com/glossary/results-and-typedresults)

## Cheat sheets

- [Your First Minimal API](https://www.ask-codey.com/cheat-sheets/minimal-apis-your-first-minimal-api-cheat-sheet)

Source: https://www.ask-codey.com/lessons/minimal-apis-your-first-minimal-api
