Your first ASP.NET Core Web API in 5 mins

What's ASP.NET Core?

For simple, ASP.NET Core is a web backend framework made by Microsoft. You can create the website, API interface, backend service. It's cross-platform (Windows, macOS, Linux) and open source.

There is a Minimal API after .NET 6, the advantage is that you don't need to create a lot of files and classes, only a few line codes then will be easy to create a web service. It's friendly for the beginner that don't need to understand the MVC, Controller and Startup concepts.

Let's use the Minimal API to create a simple Web API.

What's need to be installed?

Only one: .NET SDK

Download the latest .Net SDK version (Should be .Net 10 now), after installed, open your console and run below command for check the .Net version:

dotnet --version

If you see the .Net version (10.0.301) then will be done! You can use any IDE what you like: VS Code, Visual Studio, Rider; and I would like to use VS Code :)

Step 1. Create the project

Create a folder name : MyFirstApi and then run below commands in your folder:

dotnet new webapi -n MyFirstApi

dotnet new webapi command will generate a minimal Web API project, the structure as below

MyFirstApi/
├── Program.cs          # Entrance to the entire program, all codes are here
├── MyFirstApi.csproj   # Project file (same as package.json)
├── appsettings.json    # config file
└── Properties/
    └── launchSettings.json

Yes, that's all! All the codes will be in Program.cs file for a Web API service.

Step 2. Let's start coding

Open Program.cs, delete all the default codes and just past the below codes

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

app.MapGet("/", () => "Hello World!");

app.Run();

only 5 lines codes will be done, let's see what are their means:

• var builder = WebApplication.CreateBuilder(args); -- Create a builder for an application to the configuration
• var app = builder.Build(); -- Build the application
• app.MapGet("/", () => "Hello World!"); -- Register an interface, it will return "Hello World!" words when using HTTP GET to access the root folder '/'
• app.Run(); -- Startup the service to watch the HTTP request

Please note that the / and Hello World！ in MapGet -- The / is a path and Hello World！ is the return value, this is the core format of the Minimal API.

Step 3. Running the project

Run the below command in project folder

dotnet run

After a few seconds, you will see the below in console

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001

If you see Now listening on then the service is running, you can access http://localhost:5000 in your browser, you will see Hello World!

Also, you can use curl for testing

curl http://localhost:5000
# output: Hello World!

You can press Ctrl + C to stop the service.

Step 4. Add the custom logics

It's not enough with only a Hello World! , let's add more interfaces!

The parameters of router

Update Program.cs as below:

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

app.MapGet("/", () => "Hello World!");

// with parameter
app.MapGet("/greet/{name}", (string name) => $"Hello, {name}!");

// multiple parameters
app.MapGet("/sum/{a}/{b}", (int a, int b) => a + b);

app.Run();

Run the dotnet run again, then try below commands

curl http://localhost:5000/greet/Winson
# Output: Hello, Winson!

curl http://localhost:5000/sum/3/5
# Output: 8

The {name},{a} and {b} are the parameters of the router. C# will auto convert the value type (string/int) into these parameters

Return the JSON object

API interfaces most often return JSON. So we update the codes as below:

app.MapGet("/user/{id}", (int id) => new
{
    Id = id,
    Name = "Winson",
    Email = "winson@example.com",
    CreatedAt = DateTime.UtcNow
});

Request it

curl http://localhost:5000/user/42

Output (after formatted)

{
  "id": 42,
  "name": "Winson",
  "email": "winson@example.com",
  "createdAt": "2026-09-05T15:00:00.000Z"
}

In C#, the syntax new { ... } is called an anonymous object, and ASP.NET Core will automatically serialize it into JSON and return it. No additional configuration is required.

Get the request as JSON with POST method

app.MapPost("/user", (User user) => Results.Ok(new
{
    Message = "The user has been created",
    User = user
}));

app.Run();

// Define an User record (must be put after the app.Run())
record User(string Name, int Age);

Please note that the line record User(string Name, int Age) - this is the record type after C# 9. You can define an immutable data class in one line, which is much simpler than the traditional class.

Try to use curl to send a POST request:

curl -X POST http://localhost:5000/user \
  -H "Content-Type: application/json" \
  -d '{"name":"Winson","age":28}'

Output:

{
  "message": "The user has been created",
  "user": {
    "name": "Winson",
    "age": 28
  }
}

ASP.NET Core automatically deserializes the JSON in the request into a User object, which is then passed directly as a parameter. This is model binding for the Minimal API, which is very convenient.

The final completed codes

We put all codes together, a Web API with GET, POST, Router Parameters, JSON handler as below:

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

record User(string Name, int Age);

app.MapGet("/", () => "Hello World!");

app.MapGet("/greet/{name}", (string name) => $"Hello, {name}!");

app.MapGet("/sum/{a}/{b}", (int a, int b) => a + b);

app.MapGet("/user/{id}", (int id) => new
{
    Id = id,
    Name = "Winson",
    Email = "winson@example.com"
});

app.MapPost("/user", (User user) => Results.Ok(new
{
    Message = "The user has been created",
    User = user
}));

app.Run();

It's less than 30 lines of code in total. Compare it to Node.js's Express or Python's Flask, and you'll find that the Minimal API is very similar in syntax—both register a path and a handler function.

Conclusion

This article covers the core knowledge points of the ASP.NET Core Minimal API:

• dotnet new webapi create a Web API project
• app.MapGet / app.MapPost register an interface
• use {parameter} to add the router's parameter
• C# can automatically convert objects to JSON, or convert JSON to objects.
• record is an easy way to define a simple data type

What to Learn Next

• Dependency Injection (DI): Injecting databases and services into the API.

• Entity Framework Core: Connecting to the database and performing CRUD operations.

• Middleware: Understanding how requests flow through your application.

• Authentication: Adding JWT authentication.

But these are all things to consider later. First, get the examples in this article working before thinking about the next step. If it doesn't work, repeatedly run dotnet run and check the logs. The most common mistake for beginners is a pre-existing port (changing the port or killing the process using it will solve the problem).

Writing a working API isn't that difficult, right? Go try it out; the moment it runs is more effective than reading 10 tutorials.