{"id":32,"date":"2024-02-27T14:33:09","date_gmt":"2024-02-27T14:33:09","guid":{"rendered":"https:\/\/twobitranch.io\/?p=32"},"modified":"2026-09-18T13:12:31","modified_gmt":"2026-09-18T13:12:31","slug":"net-and-minimal-apis","status":"publish","type":"post","link":"https:\/\/twobitranch.io\/index.php\/2024\/02\/27\/net-and-minimal-apis\/","title":{"rendered":".NET Minimal APIs:"},"content":{"rendered":"\n

<\/p>\n\n\n\n

Apparently We\u2019ve Finally Admitted Controllers Were a Mistake<\/h2>\n\n\n\n

An entirely unbiased account from a developer who has been writing front ends, back ends, and increasingly desperate resignation letters for about 30 years.<\/em><\/p>\n\n\n\n

I have been a software developer for roughly 30 years.<\/p>\n\n\n\n

That means I have witnessed the entire evolution of web development, from:<\/p>\n\n\n\n

\n

\u201cLet\u2019s put some HTML on a server.\u201d<\/p>\n<\/blockquote>\n\n\n\n

to:<\/p>\n\n\n\n

\n

\u201cLet\u2019s build a distributed, event-driven, cloud-native, containerized, observable, horizontally scalable platform that renders a button.\u201d<\/p>\n<\/blockquote>\n\n\n\n

I have used technologies whose names have since been erased from the archaeological record.<\/p>\n\n\n\n

I remember when we thought frames were a good idea.<\/p>\n\n\n\n

I remember when JavaScript was something you apologized for putting on a page.<\/p>\n\n\n\n

I remember when XML was going to solve everything.<\/p>\n\n\n\n

I remember when SOAP was going to solve everything.<\/p>\n\n\n\n

I remember when REST was going to solve everything.<\/p>\n\n\n\n

I have learned one important thing from all of this:<\/p>\n\n\n\n

We are really bad at leaving well enough alone.<\/strong><\/p>\n\n\n\n

And then along came .NET Minimal APIs.<\/p>\n\n\n\n

And I thought:<\/p>\n\n\n\n

\u201cWait a minute.<\/p>\n\n\n\n

Are we\u2026 just writing functions now?\u201d<\/p>\n\n\n\n

Apparently.<\/p>\n\n\n\n

\n\n\n\n

The Good Old Days<\/h2>\n\n\n\n

When I started building web applications, the web stack was delightfully primitive.<\/p>\n\n\n\n

You had a server.<\/p>\n\n\n\n

You had a database.<\/p>\n\n\n\n

You had HTML.<\/p>\n\n\n\n

You had some JavaScript, although admitting this publicly could get you fired.<\/p>\n\n\n\n

And you had a vague understanding that HTTP involved something called GET and POST.<\/p>\n\n\n\n

Then frameworks arrived.<\/p>\n\n\n\n

And frameworks did what frameworks do best:<\/p>\n\n\n\n

They created an enormous amount of infrastructure to protect you from having to write three lines of code.<\/strong><\/p>\n\n\n\n

Before long, creating an endpoint required approximately seventeen files.<\/p>\n\n\n\n

You had:<\/p>\n\n\n\n

    \n
  • A controller<\/li>\n\n\n\n
  • An interface<\/li>\n\n\n\n
  • A service<\/li>\n\n\n\n
  • A service implementation<\/li>\n\n\n\n
  • A repository<\/li>\n\n\n\n
  • A repository interface<\/li>\n\n\n\n
  • A DTO<\/li>\n\n\n\n
  • A DTO mapper<\/li>\n\n\n\n
  • A validator<\/li>\n\n\n\n
  • A dependency injection registration<\/li>\n\n\n\n
  • An extension method to register the dependency injection registration<\/li>\n\n\n\n
  • A configuration class<\/li>\n\n\n\n
  • An options class<\/li>\n\n\n\n
  • An AutoMapper profile<\/li>\n\n\n\n
  • A unit test<\/li>\n\n\n\n
  • A mock of the repository<\/li>\n\n\n\n
  • A mock of the service<\/li>\n\n\n\n
  • A mock of the mapper<\/li>\n\n\n\n
  • And, if you were really serious, a factory for the mock factory<\/li>\n<\/ul>\n\n\n\n

    Eventually someone would ask:<\/p>\n\n\n\n

    \n

    \u201cCan you add an endpoint that returns a customer by ID?\u201d<\/p>\n<\/blockquote>\n\n\n\n

    And you’d say:<\/p>\n\n\n\n

    \n

    \u201cSure. Give me two days.\u201d<\/p>\n<\/blockquote>\n\n\n\n

    \n\n\n\n

    Enter Minimal APIs<\/h1>\n\n\n\n

    Then Microsoft basically looked at all of this and said:<\/p>\n\n\n\n

    \n

    \u201cWhat if you just\u2026 didn’t?\u201d<\/p>\n<\/blockquote>\n\n\n\n

    And thus Minimal APIs were born.<\/p>\n\n\n\n

    You can now write something like:<\/p>\n\n\n\n

    app.MapGet(\"\/customers\/{id}\", async (int id, MyDbContext db) =>\n{\n    return await db.Customers.FindAsync(id);\n});<\/code><\/pre>\n\n\n\n
    That’s it.<\/p>\n\n\n\n
    That’s the endpoint.<\/p>\n\n\n\n
    There isn’t a controller.<\/p>\n\n\n\n
    There isn’t a controller factory.<\/p>\n\n\n\n
    There isn’t a controller interface.<\/p>\n\n\n\n
    There isn’t a controller base class.<\/p>\n\n\n\n
    There isn’t a controller factory factory.<\/p>\n\n\n\n
    There is just:<\/p>\n\n\n\n
    GET \/customers\/42<\/code><\/strong><\/p>\n\n\n\n
    and some C#.<\/p>\n\n\n\n
    At first, I didn’t trust it.<\/p>\n\n\n\n
    I’ve been doing this too long.<\/p>\n\n\n\n
    Whenever something looks simple, I immediately assume Microsoft has hidden something horrible behind it.<\/p>\n\n\n\n
    \n\n\n\n
    \u201cBut Where’s the Controller?\u201d<\/h1>\n\n\n\n
    This is the first question every veteran developer asks.<\/p>\n\n\n\n
    You see:<\/p>\n\n\n\n
    app.MapGet(\"\/orders\/{id}\", (int id) =>\n{\n    return GetOrder(id);\n});<\/code><\/pre>\n\n\n\n
    And your brain immediately starts looking around the room.<\/p>\n\n\n\n
    \u201cWhere’s the controller?\u201d<\/p>\n\n\n\n
    Nothing.<\/p>\n\n\n\n
    \u201cWhere’s the action method?\u201d<\/p>\n\n\n\n
    That’s it.<\/p>\n\n\n\n
    \u201cWhere’s the attribute?\u201d<\/p>\n\n\n\n
    There isn’t one.<\/p>\n\n\n\n
    \u201cWhere’s the base class?\u201d<\/p>\n\n\n\n
    There isn’t one.<\/p>\n\n\n\n
    \u201cWhere do I put [Authorize]<\/code>?\u201d<\/p>\n\n\n\n
    Right there.<\/p>\n\n\n\n
    \u201cWhere do I put [ProducesResponseType]<\/code>?\u201d<\/p>\n\n\n\n
    Right there.<\/p>\n\n\n\n
    \u201cWhere’s the 900-line startup configuration file?\u201d<\/p>\n\n\n\n
    Gone.<\/p>\n\n\n\n
    At this point you become suspicious.<\/p>\n\n\n\n
    You start walking around the codebase looking behind things.<\/p>\n\n\n\n
    \n\n\n\n
    The Front-End Developer’s Perspective<\/h1>\n\n\n\n
    I’ve spent decades doing both front-end and back-end development, which means I have developed the unique ability to be disappointed by both sides of the application.<\/p>\n\n\n\n
    The front end says:<\/p>\n\n\n\n
    \n
    \u201cThe API is returning the wrong shape.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    The back end says:<\/p>\n\n\n\n
    \n
    \u201cThe front end is consuming the API incorrectly.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    The database says:<\/p>\n\n\n\n
    \n
    \u201cBoth of you are idiots.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    Minimal APIs actually make this relationship slightly more honest.<\/p>\n\n\n\n
    Your endpoint is sitting there in plain sight:<\/p>\n\n\n\n
    app.MapPost(\"\/products\", async (Product product, MyDbContext db) =>\n{\n    db.Products.Add(product);\n    await db.SaveChangesAsync();\n\n    return Results.Created($\"\/products\/{product.Id}\", product);\n});<\/code><\/pre>\n\n\n\n
    The front-end developer can look at it and understand what is happening.<\/p>\n\n\n\n
    The back-end developer can look at it and understand what is happening.<\/p>\n\n\n\n
    The database developer can look at it and say:<\/p>\n\n\n\n
    \n
    \u201cWhy are you returning the entity?\u201d<\/p>\n<\/blockquote>\n\n\n\n
    And thus, balance is restored to the universe.<\/p>\n\n\n\n
    \n\n\n\n
    The Beautiful Thing About Minimal APIs<\/h1>\n\n\n\n
    Minimal APIs acknowledge something we’ve collectively refused to admit for decades:<\/p>\n\n\n\n
    Sometimes an endpoint is just an endpoint.<\/strong><\/p>\n\n\n\n
    Sometimes you don’t need an architectural ceremony around it.<\/p>\n\n\n\n
    Sometimes:<\/p>\n\n\n\n
    HTTP request\n   \u2193\ndo thing\n   \u2193\nHTTP response<\/code><\/pre>\n\n\n\n
    is actually a perfectly respectable architecture.<\/p>\n\n\n\n
    This is especially useful for small services.<\/p>\n\n\n\n
    Health checks.<\/p>\n\n\n\n
    Webhooks.<\/p>\n\n\n\n
    Internal APIs.<\/p>\n\n\n\n
    Tiny microservices.<\/p>\n\n\n\n
    Background-service control endpoints.<\/p>\n\n\n\n
    Prototypes.<\/p>\n\n\n\n
    Administrative APIs.<\/p>\n\n\n\n
    That one endpoint you needed because somebody in accounting wants to trigger a nightly report by hitting a URL.<\/p>\n\n\n\n
    For those things, Minimal APIs are fantastic.<\/p>\n\n\n\n
    You don’t need to construct the Cathedral of Notre Dame because someone asked for a GET endpoint.<\/p>\n\n\n\n
    \n\n\n\n
    But Then We Discover Dependency Injection<\/h1>\n\n\n\n
    Here’s where things get interesting.<\/p>\n\n\n\n
    Minimal APIs support dependency injection directly in handler parameters.<\/p>\n\n\n\n
    So this:<\/p>\n\n\n\n
    app.MapGet(\"\/customers\/{id}\",\n    async (int id, CustomerService service) =>\n        await service.GetCustomer(id));<\/code><\/pre>\n\n\n\n
    is perfectly reasonable.<\/p>\n\n\n\n
    And suddenly I’m thinking:<\/p>\n\n\n\n
    \n
    \u201cWait. This is actually pretty nice.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    The framework sees CustomerService<\/code> and says:<\/p>\n\n\n\n
    \n
    \u201cOh, you need one of those? Here.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    The handler gets its dependencies.<\/p>\n\n\n\n
    Nobody has to manually dig around inside some mystical HttpContext.Services<\/code> object like they’re searching for a lost contact lens.<\/p>\n\n\n\n
    You can even inject multiple dependencies:<\/p>\n\n\n\n
    app.MapGet(\"\/reports\",\n    async (\n        ReportService reports,\n        ILogger<Program> logger,\n        IConfiguration config,\n        CancellationToken cancellationToken) =>\n    {\n        logger.LogInformation(\"Generating report\");\n\n        return await reports.GenerateAsync(cancellationToken);\n    });<\/code><\/pre>\n\n\n\n
    At this point, the method signature starts looking like the guest list at a family reunion.<\/p>\n\n\n\n
    But at least it’s honest.<\/p>\n\n\n\n
    \n\n\n\n
    Filters: Because We Can’t Have Nice Things<\/h1>\n\n\n\n
    Eventually someone says:<\/p>\n\n\n\n
    \n
    \u201cThis is great, but we need cross-cutting concerns.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    And the veteran developer’s eye twitches.<\/p>\n\n\n\n
    Because we know what happens next.<\/p>\n\n\n\n
    Someone needs:<\/p>\n\n\n\n
      \n
    • authorization<\/li>\n\n\n\n
    • validation<\/li>\n\n\n\n
    • logging<\/li>\n\n\n\n
    • exception handling<\/li>\n\n\n\n
    • telemetry<\/li>\n\n\n\n
    • rate limiting<\/li>\n\n\n\n
    • transactions<\/li>\n\n\n\n
    • auditing<\/li>\n\n\n\n
    • correlation IDs<\/li>\n\n\n\n
    • request timing<\/li>\n\n\n\n
    • feature flags<\/li>\n\n\n\n
    • some weird business rule from 2017<\/li>\n<\/ul>\n\n\n\n
      And suddenly our beautiful little Minimal API endpoint has become:<\/p>\n\n\n\n
      app.MapPost(\"\/widgets\",\n    async (\n        WidgetRequest request,\n        WidgetService service,\n        Validator validator,\n        AuditService audit,\n        ILogger<Program> logger,\n        CancellationToken cancellationToken) =>\n    {\n        ...\n    })\n    .RequireAuthorization()\n    .AddEndpointFilter<ValidationFilter>()\n    .AddEndpointFilter<AuditFilter>();<\/code><\/pre>\n\n\n\n
      Congratulations.<\/p>\n\n\n\n
      We have reinvented enterprise architecture.<\/p>\n\n\n\n
      It took approximately 11 minutes.<\/p>\n\n\n\n
      \n\n\n\n
      The Endpoint Group<\/h1>\n\n\n\n
      Minimal APIs do have a nice answer to this.<\/p>\n\n\n\n
      Groups.<\/p>\n\n\n\n
      You can do something like:<\/p>\n\n\n\n
      var admin = app.MapGroup(\"\/admin\")\n    .RequireAuthorization(\"AdminPolicy\");\n\nadmin.MapGet(\"\/users\", ...);\nadmin.MapGet(\"\/reports\", ...);\nadmin.MapDelete(\"\/users\/{id}\", ...);<\/code><\/pre>\n\n\n\n
      This is one of those features where you stare at it for a moment and think:<\/p>\n\n\n\n
      \n
      \u201cThat’s actually sensible.\u201d<\/p>\n<\/blockquote>\n\n\n\n
      Which is always dangerous.<\/p>\n\n\n\n
      Because the next meeting will inevitably contain the phrase:<\/p>\n\n\n\n
      \n
      \u201cLet’s create a generic endpoint group abstraction.\u201d<\/p>\n<\/blockquote>\n\n\n\n
      And now you’re back to square one.<\/p>\n\n\n\n
      \n\n\n\n
      OpenAPI: The Thing We Used to Call Swagger<\/h1>\n\n\n\n
      One of the things I genuinely appreciate about modern .NET is how much API metadata can be generated without turning the application into a ritual sacrifice.<\/p>\n\n\n\n
      Minimal APIs integrate nicely with OpenAPI tooling.<\/p>\n\n\n\n
      You can define an endpoint:<\/p>\n\n\n\n
      app.MapGet(\"\/customers\/{id}\",\n    async (int id, CustomerService service) =>\n        await service.Get(id));<\/code><\/pre>\n\n\n\n
      and expose useful API documentation.<\/p>\n\n\n\n
      This is important because apparently we have reached the point in civilization where humans can build distributed systems spanning twelve countries but still need a webpage to tell them whether an endpoint expects:<\/p>\n\n\n\n
      {\n    \"customerId\": 123\n}<\/code><\/pre>\n\n\n\n
      or:<\/p>\n\n\n\n
      {\n    \"id\": 123\n}<\/code><\/pre>\n\n\n\n
      or:<\/p>\n\n\n\n
      {\n    \"customer_id\": 123\n}<\/code><\/pre>\n\n\n\n
      or, my personal favorite:<\/p>\n\n\n\n
      {\n    \"customer\": {\n        \"customer\": {\n            \"customerId\": 123\n        }\n    }\n}<\/code><\/pre>\n\n\n\n
      OpenAPI exists because apparently naming things was the second-hardest problem in computer science.<\/p>\n\n\n\n
      \n\n\n\n
      The Problem: You Can Make a Horrible Minimal API<\/h1>\n\n\n\n
      This is the part where I have to issue a warning.<\/p>\n\n\n\n
      Minimal APIs make it extremely easy to write bad code.<\/p>\n\n\n\n
      You can absolutely do this:<\/p>\n\n\n\n
      app.MapPost(\"\/orders\", async (\n    Order order,\n    SqlConnection connection,\n    ILogger<Program> logger) =>\n{\n    \/\/ 900 lines of business logic\n});<\/code><\/pre>\n\n\n\n
      Please don’t.<\/p>\n\n\n\n
      That’s not a Minimal API.<\/p>\n\n\n\n
      That’s a cry for help.<\/p>\n\n\n\n
      The fact that you can<\/em> put everything into Program.cs<\/code> does not mean you should.<\/p>\n\n\n\n
      We’ve learned this lesson before.<\/p>\n\n\n\n
      In the 1990s we put everything into one HTML page.<\/p>\n\n\n\n
      Then we put everything into one JavaScript file.<\/p>\n\n\n\n
      Then we put everything into one controller.<\/p>\n\n\n\n
      Then we put everything into one service.<\/p>\n\n\n\n
      Now we are being offered Program.cs<\/code>.<\/p>\n\n\n\n
      Do not make the same mistake again.<\/strong><\/p>\n\n\n\n
      \n\n\n\n
      Minimal Does Not Mean Architectural<\/h1>\n\n\n\n
      This distinction is important.<\/p>\n\n\n\n
      Minimal APIs are about reducing the ceremony around HTTP endpoints.<\/p>\n\n\n\n
      They don’t magically eliminate:<\/p>\n\n\n\n
        \n
      • business logic<\/li>\n\n\n\n
      • domain modeling<\/li>\n\n\n\n
      • persistence concerns<\/li>\n\n\n\n
      • security<\/li>\n\n\n\n
      • testing<\/li>\n\n\n\n
      • observability<\/li>\n\n\n\n
      • validation<\/li>\n\n\n\n
      • maintainability<\/li>\n<\/ul>\n\n\n\n
        You still need architecture.<\/p>\n\n\n\n
        You just don’t necessarily need architecture cosplay<\/strong>.<\/p>\n\n\n\n
        There’s a difference between:<\/p>\n\n\n\n
        \n
        \u201cWe have a clean separation of concerns.\u201d<\/p>\n<\/blockquote>\n\n\n\n
        and:<\/p>\n\n\n\n
        \n
        \u201cWe have 46 projects so nobody can figure out where the code lives.\u201d<\/p>\n<\/blockquote>\n\n\n\n
        I’ve worked on both.<\/p>\n\n\n\n
        I know which one I prefer.<\/p>\n\n\n\n
        \n\n\n\n
        Thirty Years of Front-End Development Has Taught Me One Thing<\/h1>\n\n\n\n
        The back end and front end have more in common than we like to admit.<\/p>\n\n\n\n
        Front-end developers spent years trying to make HTML simpler.<\/p>\n\n\n\n
        Then we invented:<\/p>\n\n\n\n