Building REST APIs with ASP.NET Core

A minimal API for a Todo resource. The comments show the exact HTTP response for each call.

// Program.cs — a minimal API (ASP.NET Core 8+)
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// An in-memory "resource" collection. Each Todo is a RESOURCE the API exposes.
var todos = new List<Todo>
{
    new(1, "Learn C#", true),
    new(2, "Build an API", false)
};
var nextId = 3;

// GET = READ a collection.  Always returns 200 OK with the data.
app.MapGet("/api/todos", () => Results.Ok(todos));
//   GET /api/todos           -> 200 OK   [{ "id":1, ... }, { "id":2, ... }]

// GET one resource by id.  Found -> 200 OK, missing -> 404 Not Found.
app.MapGet("/api/todos/{id}", (int id) =>
{
    var todo = todos.FirstOrDefault(t => t.Id == id);
    return todo is not null ? Results.Ok(todo) : Results.NotFound();
});
//   GET /api/todos/1         -> 200 OK   { "id":1, "title":"Learn C#", "isDone":true }
//   GET /api/todos/99        -> 404 Not Found

// POST = CREATE.  Returns 201 Created + a Location header to the new resource.
app.MapPost("/api/todos", (CreateTodoDto dto) =>
{
    var todo = new Todo(nextId++, dto.Title, false);
    todos.Add(todo);
    return Results.Created($"/api/todos/{todo.Id}", todo);
});
//   POST /api/todos  { "title":"Ship it" }  -> 201 Created  Location: /api/todos/3

// PUT = REPLACE/UPDATE an existing resource.  Returns 200 OK or 404.
app.MapPut("/api/todos/{id}", (int id, UpdateTodoDto dto) =>
{
    var i = todos.FindIndex(t => t.Id == id);
    if (i == -1) return Results.NotFound();
    todos[i] = todos[i] with { Title = dto.Title, IsDone = dto.IsDone };
    return Results.Ok(todos[i]);
});
//   PUT /api/todos/1  { "title":"Learn C# well", "isDone":true } -> 200 OK

// DELETE = REMOVE.  Returns 204 No Content (success, nothing to send back).
app.MapDelete("/api/todos/{id}", (int id) =>
    todos.RemoveAll(t => t.Id == id) > 0 ? Results.NoContent() : Results.NotFound());
//   DELETE /api/todos/2      -> 204 No Content
//   DELETE /api/todos/99     -> 404 Not Found

app.Run();

// Records make tidy DTOs — the SHAPE the API sends and receives.
record Todo(int Id, string Title, bool IsDone);
record CreateTodoDto(string Title);
record UpdateTodoDto(string Title, bool IsDone);

This needs a web server, so it won't run in the browser runner — but you'll model its logic in the runnable exercise just below.

The same kind of API as a controller — with model binding, DTOs, and versioning in the route.

using Microsoft.AspNetCore.Mvc;

// Controllers/ProductsController.cs
[ApiController]                       // turns on auto model binding + auto 400 on invalid input
[Route("api/v1/[controller]")]        // [controller] -> "products". Route: /api/v1/products
public class ProductsController : ControllerBase
{
    private static readonly List<Product> _products = new()
    {
        new() { Id = 1, Name = "Laptop", Price = 999.99m },
        new() { Id = 2, Name = "Mouse",  Price = 24.99m }
    };

    // GET /api/v1/products?minPrice=100   ([FromQuery] = read from the query string)
    [HttpGet]
    public ActionResult<IEnumerable<ProductDto>> GetAll([FromQuery] decimal? minPrice)
    {
        var items = _products.Where(p => minPrice is null || p.Price >= minPrice);
        // Map ENTITIES -> DTOs so the API shape never leaks internal columns.
        return Ok(items.Select(p => new ProductDto(p.Id, p.Name, p.Price)));
    }
    //   GET /api/v1/products?minPrice=100 -> 200 OK  [{ "id":1,"name":"Laptop","price":999.99 }]

    // GET /api/v1/products/1   ({id} is bound from the route by model binding)
    [HttpGet("{id:int}")]
    public ActionResult<ProductDto> GetById(int id)
    {
        var p = _products.FirstOrDefault(x => x.Id == id);
        if (p is null) return NotFound();                 // 404
        return Ok(new ProductDto(p.Id, p.Name, p.Price)); // 200
    }
    //   GET /api/v1/products/1   -> 200 OK   { "id":1, "name":"Laptop", "price":999.99 }
    //   GET /api/v1/products/99  -> 404 Not Found

    // POST /api/v1/products    ([FromBody] = bind the JSON request body to the DTO)
    [HttpPost]
    public ActionResult<ProductDto> Create([FromBody] CreateProductDto dto)
    {
        // [ApiController] already rejected an invalid body with 400 before we got here.
        var product = new Product { Id = _products.Max(p => p.Id) + 1, Name = dto.Name, Price = dto.Price };
        _products.Add(product);
        var result = new ProductDto(product.Id, product.Name, product.Price);
        return CreatedAtAction(nameof(GetById), new { id = product.Id }, result); // 201
    }
    //   POST /api/v1/products  { "name":"Keyboard", "price":59.99 }
    //     -> 201 Created   Location: /api/v1/products/3
}

// ENTITY — the internal storage shape (could map to a database row).
public class Product { public int Id; public string Name = ""; public decimal Price; }

// DTOs — the PUBLIC shape the API exposes. Never return the entity directly.
public record ProductDto(int Id, string Name, decimal Price);
public record CreateProductDto(string Name, decimal Price);

Read the [FromQuery] / [FromBody] attributes — that's model binding, covered next.