Minimal APIs Cheatsheet (in ASP.NET Core)

Introduction

Minimal APIs were introduced in .NET 6 to simplify the creation of small, fast, and lightweight web APIs. They allow developers to write API logic with less code and configuration, without needing controllers or attributes like in traditional ASP.NET MVC.

They are best used when building simple services, microservices, or proof-of-concept applications.

1. Create a New Minimal API Project

To get started

dotnet new web -n MinimalApiDemo

This template sets up a basic minimal API.
No controllers or Views folder.

2. Basic Program.cs Structure

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

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

app.Run();

MapGet defines a GET endpoint.
Everything is written in Program.cs.

3. MapGet() – Handle GET Requests

app.MapGet("/hello", () => "Hi there!");

Used to return data or simple messages.
Can return strings, objects, or JSON.

4. MapPost() – Handle POST Requests

app.MapPost("/add", (int x, int y) => x + y);

Accepts parameters directly from query or body.
Ideal for submitting data.

5. MapPut() – Handle PUT Requests

app.MapPut("/update", (int id, string name) => $"Updated {id} to {name}");

Used to update existing resources.

6. MapDelete() – Handle DELETE Requests

app.MapDelete("/delete/{id}", (int id) => $"Deleted item {id}");

Deletes a resource based on the ID.

7. Return JSON Response

app.MapGet("/user", () => new { Name = "John", Age = 25 });

Automatically serializes object to JSON.
No need for extra configuration.

8. Reading From Query Strings

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

Pass like /greet?name=Diksha.

9. Reading From Route Parameters

app.MapGet("/product/{id}", (int id) => $"Product ID: {id}");

Route parameters are defined inside {}.

10. Read JSON Body in POST

app.MapPost("/person", (Person person) =>
{
    return $"Name: {person.Name}, Age: {person.Age}";
});

record Person(string Name, int Age);

Automatically binds the JSON request body to an object.
Use record or class.

11. Dependency Injection (DI)

Register service

builder.Services.AddSingleton<MyService>();

Use it in the route

app.MapGet("/info", (MyService svc) => svc.GetInfo());

Supports constructor-less DI in lambda.

12. Validation Example

app.MapPost("/validate", (User user) =>
{
    if (string.IsNullOrWhiteSpace(user.Email))
        return Results.BadRequest("Email is required");

    return Results.Ok("Valid User");
});

record User(string Email);

Manual validation can be added easily.

13. Using Results Object

app.MapGet("/status", () => Results.Ok("Working"));
app.MapGet("/fail", () => Results.BadRequest("Something went wrong"));

Explicit control over HTTP response type and status.

14. Grouping Routes

var userGroup = app.MapGroup("/users");

userGroup.MapGet("/", () => "All users");
userGroup.MapPost("/", (User u) => $"User {u.Email} added");

Helps organize related endpoints under a common path.

15. Middleware Usage

app.Use(async (context, next) =>
{
    Console.WriteLine("Request coming in");
    await next();
    Console.WriteLine("Response going out");
});

Minimal APIs support middlewares like normal APIs.

16. Enable Swagger (OpenAPI)

Add services

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Use Swagger UI

app.UseSwagger();
app.UseSwaggerUI();

Helps with testing and documentation.

17. Route Constraints

app.MapGet("/item/{id:int}", (int id) => $"Item ID: {id}");

:int ensures only integer is accepted.

18. Allow CORS

builder.Services.AddCors();

app.UseCors(policy => policy.AllowAnyOrigin().AllowAnyHeader().AllowAnyMethod());

Enables cross-origin API calls.

19. Environment-based Configuration

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

Add environment-specific behaviors.

20. Error Handling

app.UseExceptionHandler("/error");

app.Map("/error", () => Results.Problem("Unexpected error occurred"));

Define a global error route.

21. Run on Custom URL/Port

Update launchSettings.json or in code:

builder.WebHost.UseUrls("http://localhost:5001");

22. Route Prefix with [MapGroup] for Versioning

var v1 = app.MapGroup("/api/v1");

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

Helps version your API easily (/api/v1/products).

23. Use Authorization

builder.Services.AddAuthorization();
app.UseAuthorization();

app.MapGet("/secure", () => "Secure Data")
   .RequireAuthorization();

Supports role-based or policy-based authorization.

24. Async Endpoints

app.MapGet("/delay", async () =>
{
    await Task.Delay(1000);
    return "Done after delay";
});

All endpoints can be asynchronous using async/await.

25. Binding From Headers / Claims

app.MapGet("/agent", (HttpRequest req) =>
{
    var userAgent = req.Headers["User-Agent"];
    return $"Your agent: {userAgent}";
});

Use HttpRequest or HttpContext to access headers, claims, cookies, etc.

26. Custom Response Codes

app.MapGet("/notfound", () => Results.StatusCode(404));

Fine-grained control over HTTP response codes.

27. Conditional Endpoints (MapWhen)

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/admin"), appBuilder =>
{
    appBuilder.Run(async ctx => await ctx.Response.WriteAsync("Admin section"));
});

Handle advanced routing logic manually.

28. Bind Form Data

app.MapPost("/upload", async (HttpRequest req) =>
{
    var form = await req.ReadFormAsync();
    var file = form.Files["file"];
    return $"Uploaded: {file?.FileName}";
});

Useful for uploading files or handling multipart/form-data.

29. Handle Query, Route, and Body Together

app.MapPost("/mixed/{id}", (int id, string name, MyData data) =>
{
    return $"ID: {id}, Name: {name}, Data: {data.Value}";
});

record MyData(string Value);

You can mix route, query, and body parameters.

Comparison: Minimal APIs vs Traditional RESTful APIs (Controllers)

Feature	Minimal APIs	RESTful APIs (Controllers)
Setup	Very low setup, all in `Program.cs`	Needs controllers, attributes, and routing setup
Performance	Slightly better (fewer layers)	Slightly heavier due to abstraction layers
Best For	Small services, microservices, and quick APIs	Large-scale apps with many endpoints
Testability	Less structured, harder to unit test	Easier to test with controllers/services
Routing	Code-based (inline)	Attribute routing or convention-based
Dependency Injection	Direct in lambda	Via constructor injection in controllers
Maintainability (Large apps)	Harder to scale/organize	Better separation of concerns
Swagger Support	Fully supported	Fully supported
Custom Filters / Middleware	Limited (no filters, but use middleware)	Full support (filters, middleware, etc.)
Validation (FluentValidation, etc.)	Manual or via packages	Built-in integration via ModelState
Extensibility	Limited to what's in lambdas/middleware	Highly extensible (Filters, Bindings, etc.)

When to Use What?

Use Case	Recommendation
Quick prototype or POC	Minimal API
Microservices / serverless	Minimal API
Full-blown business app	RESTful API (Controllers)
App needing filters/attributes	RESTful API
Highly structured/maintainable code	RESTful API

Conclusion

Minimal APIs are a powerful tool for quickly building web APIs with clean and minimal code. They reduce boilerplate and work great for microservices or simple services. But for complex systems, RESTful APIs using controllers still offer more structure and long-term scalability.

Use Minimal APIs when you want speed and simplicity, but switch to RESTful APIs when you need organization, structure, testability, or layered architecture.