ASP.NET Core: your first Web API

What is a Web API?

When you open the Zomato app, the app on your phone does not contain the restaurant list. It sends an HTTP request over the internet to a server, and the server replies with data in JSON. That server program is a Web API. API means Application Programming Interface: a way for programs to talk to each other.

Create and run a project

dotnet new webapi -o ShopApi
cd ShopApi
dotnet run

The template includes a sample /weatherforecast endpoint, a .http file you can use to send test requests from VS Code or Visual Studio, and OpenAPI support (a machine-readable description of your API). Recent templates generate the OpenAPI document but do not include a browsing UI by default; you can add one such as Swagger UI or Scalar, or test with the .http file, curl or Postman.

The smallest API

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "ShopApi is running");
app.MapGet("/time", () => new { Now = DateTime.Now });

app.Run();

curl http://localhost:5000/time
{"now":"2026-05-04T10:15:30.123+05:30"}

A small in-memory product API

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var products = new List<Product>
{
    new(1, "Steel bottle", 349m),
    new(2, "Cotton kurta", 799m)
};

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

app.MapGet("/products/{id:int}", (int id) =>
    products.FirstOrDefault(p => p.Id == id) is Product p
        ? Results.Ok(p)
        : Results.NotFound());

app.MapPost("/products", (Product input) =>
{
    var created = input with { Id = products.Max(p => p.Id) + 1 };
    products.Add(created);
    return Results.Created($"/products/{created.Id}", created);
});

app.Run();

public record Product(int Id, string Name, decimal Price);

Controllers: the class-based style

Before minimal APIs (added in .NET 6), every ASP.NET Core API used controllers, and many company projects still do. A controller is a class whose public methods (actions) handle requests. Create a project with them using dotnet new webapi --use-controllers.

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]          // becomes api/products
public class ProductsController : ControllerBase
{
    private static readonly List<Product> Products = new() { new(1, "Steel bottle", 349m) };

    [HttpGet]
    public IEnumerable<Product> GetAll() => Products;

    [HttpGet("{id:int}")]
    public ActionResult<Product> GetById(int id)
    {
        var p = Products.FirstOrDefault(x => x.Id == id);
        return p is null ? NotFound() : Ok(p);
    }
}

Common mistakes and fixes

• Following an old tutorial with Startup.cs and ConfigureServices: that was the .NET Core 3 to 5 style. Since .NET 6 everything starts in Program.cs. The ideas are the same.
• Forgetting app.Run(): the app builds and exits immediately.
• Forgetting AddControllers and MapControllers: controllers exist but every URL returns 404.
• Returning null for "not found": the client gets 204 or 200 with no body. Return Results.NotFound() / NotFound() so the client gets 404.