Building Your First Minimal Web API in .NET 9

🧭 Introduction

ASP.NET Core in .NET 9 makes it easier than ever to build fast and lightweight REST APIs using Minimal APIs. These are ideal for small apps, microservices, and learning the ropes.

This tutorial walks you step by step through creating a simple API that manages a to-do list.

🧰 Prerequisites

.NET 9 SDK

A code editor like Visual Studio Code

Basic C# knowledge

🛠️ Step 1: Create a New Project

Open your terminal and run:

dotnet new webapi -n TodoApi -minimal
cd TodoApi

This creates a Minimal API project with a basic HTTP request pipeline and no MVC boilerplate.

What’s inside the project?

• Program.cs: where the whole app is defined.

• appsettings.json: configuration file.

• No controllers, no views — just pure endpoint mapping.

📄 Step 2: Add a Todo Record Model

Create a new file named Todo.cs and paste this:

namespace TodoApi;

public record Todo(int Id, string Title, bool IsDone);

record is perfect for immutable, lightweight data containers. It automatically generates constructor, ToString(), equality methods, etc.

📌 Step 3: Define Endpoints in Program.cs

Open Program.cs and replace the contents with this:

using TodoApi;

var builder = WebApplication.CreateBuilder(args);

// Register API explorer and Swagger for documentation
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(); // .NET 9 feature

var app = builder.Build();

// In-memory list to store todos
var todos = new List<Todo>();

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

// Get a specific todo
app.MapGet("/todos/{id:int}", (int id) =>
{
    var todo = todos.FirstOrDefault(t => t.Id == id);
    return todo is not null ? Results.Ok(todo) : Results.NotFound();
});

// Add a new todo
app.MapPost("/todos", (Todo todo) =>
{
    var newTodo = todo with { Id = todos.Count + 1 };
    todos.Add(newTodo);
    return Results.Created($"/todos/{newTodo.Id}", newTodo);
});

// Start the app
app.Run();

🔍 Key Concepts

• MapGet and MapPost are routing methods.

• Results.Ok(), Results.NotFound(), etc. return HTTP responses.

• The todo list is in-memory — no database for now.

• This approach is clean, short, and great for beginners.

🚀 Step 4: Run & Test the API

Run the project:

dotnet run

You should see something like:

Now listening on: https://localhost:5001

🔁 Test your API

Try hitting the endpoints:

curl https://localhost:5001/todos

You can also test via the built-in Swagger UI by visiting:

https://localhost:5001/swagger

This gives you an interactive interface to explore your API. 🧪

⚙️ Step 5: Publish with Ahead-of-Time Compilation (Optional)

Want to make it even faster for deployment?

.NET 9 supports native AOT publishing:

dotnet publish -c Release -p:PublishAot=true

This compiles your app down to a native binary — startup time is nearly instant.

🧠 Bonus Tips for Beginners

• ❗ This app does not persist data. Restarting the app wipes the todo list.

• ✅ Try using Postman or Thunder Client (VS Code extension) for testing.

• 📦 You can integrate with EF Core and SQLite in the next step (see Article 2!).

🏁 Conclusion

You’ve just created your first REST API using .NET 9 and C# Minimal APIs! 🎉
This pattern is beginner-friendly, fast, and scalable.