Minimal API Advanced

🚀 Minimal API Advanced: The Secret Superpowers

Imagine you’re building a LEGO castle. You already know how to snap blocks together. Now you want to add secret doors, magic paint, a treasure map, and a guard who checks everyone at the gate. That’s what we’re learning today!

🎯 What We’ll Discover

🛡️ Endpoint Filters: The Guards at the Gate

What Are They?

Think of a birthday party. Before guests come in, someone at the door:

1. Checks if they have an invitation ✉️
2. Makes sure they brought a gift 🎁
3. After the party, gives them a goodie bag 🛍️

Endpoint Filters work the same way! They run code before and after your API endpoint.

Why Use Them?

• ✅ Check if someone is allowed in (authentication)
• ✅ Write down who visited (logging)
• ✅ Measure how long things take (performance)
• ✅ Change the response before sending it back

Simple Example

app.MapGet("/hello", () => "Hi there!")
   .AddEndpointFilter(async (context, next) =>
   {
       // BEFORE: Guest arriving
       Console.WriteLine("Someone is coming!");

       // Let them in
       var result = await next(context);

       // AFTER: Guest leaving
       Console.WriteLine("Goodbye!");

       return result;
   });

Real-World Filter Class

public class LoggingFilter : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var start = DateTime.Now;

        var result = await next(context);

        var time = DateTime.Now - start;
        Console.WriteLine(quot;Took {time.TotalMilliseconds}ms");

        return result;
    }
}

Using it:

app.MapGet("/products", GetProducts)
   .AddEndpointFilter<LoggingFilter>();

Chaining Multiple Filters

Like having multiple guards, each checking different things:

app.MapPost("/order", CreateOrder)
   .AddEndpointFilter<AuthFilter>()     // Check ID
   .AddEndpointFilter<LoggingFilter>()  // Write in logbook
   .AddEndpointFilter<TimingFilter>();  // Track time

graph TD
    A["📨 Request Arrives"] --> B["🛡️ Filter 1: Auth"]
    B --> C["📝 Filter 2: Logging"]
    C --> D["⏱️ Filter 3: Timing"]
    D --> E["🎯 Your Endpoint Code"]
    E --> F["⏱️ Filter 3: Done"]
    F --> G["📝 Filter 2: Done"]
    G --> H["🛡️ Filter 1: Done"]
    H --> I["📤 Response Sent"]

📦 Results Class: Standard Message Boxes

What Is It?

When you send a letter, you put it in a standard envelope. Everyone knows how to open it!

The Results class gives you standard ways to send responses.

Common Results

Simple Example

app.MapGet("/toy/{id}", (int id) =>
{
    var toy = FindToy(id);

    if (toy == null)
        return Results.NotFound("Toy not found!");

    return Results.Ok(toy);
});

More Results You Can Use

// Redirect to another page
Results.Redirect("/new-page");

// Send a file
Results.File(bytes, "image/png");

// Send JSON data
Results.Json(myObject);

// No content (empty success)
Results.NoContent();

// Server error
Results.Problem("Something broke!");

Why Use Results?

1. Consistent: Same format every time
2. Clear: Other developers understand it
3. HTTP Standards: Follows web rules
4. Easy Testing: Simple to check in tests

🎯 TypedResults: Smart Message Boxes

The Problem with Results

Look at this code:

app.MapGet("/item/{id}", (int id) =>
{
    if (id < 0)
        return Results.BadRequest();
    return Results.Ok(new Item { Id = id });
});

Question: What does this return? 🤔

The compiler doesn’t know! It just sees IResult.

TypedResults to the Rescue!

app.MapGet("/item/{id}", Results<Ok<Item>, BadRequest> (int id) =>
{
    if (id < 0)
        return TypedResults.BadRequest();
    return TypedResults.Ok(new Item { Id = id });
});

Now the compiler knows exactly what responses are possible!

The Magic Difference

Combining Multiple Response Types

app.MapGet("/user/{id}",
    Results<Ok<User>, NotFound, BadRequest<string>>
    (int id) =>
{
    if (id < 0)
        return TypedResults.BadRequest("ID must be positive");

    var user = FindUser(id);

    if (user == null)
        return TypedResults.NotFound();

    return TypedResults.Ok(user);
});

graph TD
    A["Request: GET /user/5"] --> B{id < 0?}
    B -->|Yes| C["BadRequest 🚫"]
    B -->|No| D{User exists?}
    D -->|No| E["NotFound ❌"]
    D -->|Yes| F["Ok with User ✅"]

🗺️ OpenAPI in Minimal APIs: Your Treasure Map

What Is OpenAPI?

Imagine you built an amazing playground. But how do friends know:

• What slides exist? 🛝
• How to use the swings?
• What’s the climbing wall like?

OpenAPI creates a map of your API so everyone knows what’s available!

Setting It Up

Step 1: Add the package

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

Step 2: Enable the UI

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

Step 3: Visit /swagger - See your map! 🗺️

Adding Descriptions

app.MapGet("/toys", () => GetAllToys())
   .WithName("GetToys")
   .WithDescription("Gets all available toys")
   .WithTags("Toys");

Documenting Parameters

app.MapGet("/toy/{id}", (int id) => FindToy(id))
   .WithName("GetToyById")
   .WithOpenApi(op =>
   {
       op.Summary = "Find a toy";
       op.Description = "Finds a toy by its ID number";
       op.Parameters[0].Description = "The toy's ID";
       return op;
   });

Documenting Responses

app.MapGet("/toy/{id}", GetToy)
   .Produces<Toy>(200)        // Success with Toy
   .Produces(404)             // Not found
   .ProducesProblem(500);     // Server error

With TypedResults (Automatic!)

app.MapGet("/toy/{id}",
    Results<Ok<Toy>, NotFound> (int id) =>
{
    var toy = FindToy(id);
    return toy is not null
        ? TypedResults.Ok(toy)
        : TypedResults.NotFound();
});
// OpenAPI docs are generated automatically! ✨

✅ Minimal API Validation: Checking the Homework

Why Validate?

If someone orders a pizza with -5 toppings or an email like “not.an” email", that’s a problem!

Validation = Making sure data is correct before using it.

Method 1: Manual Validation

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

    if (user.Age < 0 || user.Age > 150)
        return Results.BadRequest("Invalid age");

    // Save user...
    return Results.Ok(user);
});

Method 2: Data Annotations

public class User
{
    [Required]
    [StringLength(50)]
    public string Name { get; set; }

    [Range(0, 150)]
    public int Age { get; set; }

    [EmailAddress]
    public string Email { get; set; }
}

Method 3: Using a Validation Filter

public class ValidationFilter<T> : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext ctx,
        EndpointFilterDelegate next)
    {
        var obj = ctx.Arguments
            .OfType<T>()
            .FirstOrDefault();

        if (obj == null)
            return Results.BadRequest("Missing data");

        var results = new List<ValidationResult>();
        var context = new ValidationContext(obj);

        if (!Validator.TryValidateObject(
            obj, context, results, true))
        {
            return Results.BadRequest(results);
        }

        return await next(ctx);
    }
}

Using the filter:

app.MapPost("/user", CreateUser)
   .AddEndpointFilter<ValidationFilter<User>>();

Method 4: FluentValidation (Popular Library)

public class UserValidator : AbstractValidator<User>
{
    public UserValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MaximumLength(50);

        RuleFor(x => x.Age)
            .InclusiveBetween(0, 150);

        RuleFor(x => x.Email)
            .EmailAddress();
    }
}

graph TD
    A["📨 Data Arrives"] --> B{Valid?}
    B -->|❌ No| C["Return Error Message"]
    B -->|✅ Yes| D["Process the Data"]
    D --> E["Send Success Response"]

🎪 Putting It All Together

Here’s a complete example using everything we learned:

var builder = WebApplication.CreateBuilder(args);

// OpenAPI setup
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Enable Swagger
app.UseSwagger();
app.UseSwaggerUI();

// Our endpoint with ALL superpowers!
app.MapPost("/toys",
    Results<Created<Toy>, BadRequest<string>>
    (Toy toy) =>
{
    if (string.IsNullOrEmpty(toy.Name))
        return TypedResults.BadRequest("Name required");

    // Save toy...
    toy.Id = GenerateId();

    return TypedResults.Created(quot;/toys/{toy.Id}", toy);
})
.AddEndpointFilter<LoggingFilter>()
.WithName("CreateToy")
.WithDescription("Creates a new toy")
.WithTags("Toys");

app.Run();

🌟 Quick Summary

🎯 Remember This!

Filters = Security guards 🛡️ Results = Standard envelopes 📧 TypedResults = Smart envelopes 📬 OpenAPI = Your API’s treasure map 🗺️ Validation = Homework checker ✅

You’ve just unlocked the advanced superpowers of Minimal APIs! Now go build something amazing! 🚀