ApiEndpoints

 

ASP.NET Core API Endpoints

A project for supporting API Endpoints in ASP.NET Core web applications.

Fast Endpoints

If you're on .NET 6 or later (if you're no longer on .NET 4.x you should be on at least .NET 8) you're probably better off using Minimal APIs than Controllers. MVC is a dull edge technology at this point. If you like the organization used by this library and the REPR Pattern in general, I am now recommending the FastEndpoints library. It has a lot of additional functionality you can use or not, but its core api endpoint functionality is very solid and fast.

Give a Star! :star:

If you like or are using this project to learn or start your solution, please give it a star. Thanks!

Discover a Practical Example

If you're eager to dive into a practical example of using Ardalis.ApiEndpoints, check out our Getting Started guide. This guide walks you through setting up your environment and creating your first API endpoint using the latest features in version 4.x.

Upgrade to 4.x Notes

The fluent generics and base types involved in ApiEndpoints were updated in version 4.x, resulting in breaking changes. The updates required should be pretty straightforward, and have a few additional features that weren't supported in previous versions.

The two main changes introduced in v4 are:

• Base classes should now use EndpointBaseSync or EndpointBaseAsync
• WithResponse has been modified to WithResult or WithActionResult

The result of an endpoint corresponds to the return type from the Handle method. Since ASP.NET Core MVC refers to these as some variation of ActionResult, that's the term we are using in this package now as well. The Response your endpoint may return refers to any data/DTO that is being sent to the client as part of the Result. If you wish to preserve your existing v3 functionality that specified WithResponse<T> you should be able to replace all such occurrences with WithActionResult<T>. However, if you need to specify a different kind of Result, such as a FileResult, you can now use something like WithResult<FileResult> to achieve this.

An endpoint that previously inherited from the synchronous BaseEndpoint should now inherit from EndpointBaseSync. Additionally, the WithResponse option now has optional non-generic versions, but if you were intending to return an ActionResult<T> you would now use WithActionResult<T> in your class definition, like so:

- public class ForecastEndpoint : BaseEndpoint
-     .WithRequest<ForecastRequestDto>
-     .WithResponse<IEnumerable<WeatherForecast>>
+ public class ForecastEndpoint : EndpointBaseSync
+     .WithRequest<ForecastRequestDto>
+     .WithActionResult<IEnumerable<WeatherForecast>>

The above change typically would not require any change to the Handle method. Endpoints that inherited from BaseAsyncEndpoint would now use EndpointBaseAsync. You can also just inherit from EndpointBase directly (without the .With* additions) which will provide you with a controller with a single Handle method without restrictions on parameter amount and type, if you need more flexibility than the fluent generic interface provides.

Upgrade to 3.x Notes

For version 3.0 we implemented a new way to define the base classes using "fluent generics". You can watch a video of what you need to know to apply them to your site here.

Table of Contents

1. Motivation

2. Introducing ASP.NET Core API Endpoints

3. Getting Started

• Set Up an Empty Web API Project

• Adding Controllers with Ardalis.ApiEndpoints

• Adding common endpoint groupings using Swagger

• File Upload Example

4. Animated Screenshots

5. Open Questions

6. Roadmap

7. Related Articles

8. Videos and Podcasts

9. Related / Similar Projects

10. Projects Using ApiEndpoints

11. Success Stories and Testimonials

1. Motivation

MVC Controllers are essentially an antipattern. They're dinosaurs. They are collections of methods that never call one another and rarely operate on the same state. They're not cohesive. They tend to become bloated and to grow out of control. Their private methods, if any, are usually only called by a single public method. Most developers recognize that controllers should be as small as possible (unscientific poll), but they're the only solution offered out of the box, so that's the tool 99% of ASP.NET Core developers use.

You can use tools like MediatR to mitigate the problem. You can read a detailed article about how to migrate from Controllers to Endpoints using MediatR. The short version is that MediatR enables you to have single-line action methods that route commands to handlers. This is objectively a better approach, resulting in more cohesive classes that better follow OO principles. But what if you didn't even need that extra plumbing?

That's what ASP.NET Core API Endpoints are all about.

Side note: Razor Pages

The .NET team already did this exact thing with razor pages. They recognized that dealing with Views, ViewModels, Controllers, and Actions was way more complicated than necessary. It required a developer to jump around between at least 3 (and often more) different folders in order to add or modify a new page/view to their project. Razor pages addressed this by rethinking the model for page-based ASP.NET Core MVC endpoints.

Razor Pages group each page's razor markup, its related action(s), and its model into two linked files. It uses the same MVC features as the rest of the platform, so you still get routing, model binding, model validation, filters, the works. You literally give up nothing. But now when you need to add or modify a page you need to look at exactly 2 files, which are linked in the IDE so you don't need to scroll around the file system looking for them.

2. Introducing ASP.NET Core API Endpoints

ASP.NET Core API Endpoints are essentially Razor Pages for APIs. They break apart bloated controllers and group the API models used by individual endpoints with the endpoint logic itself. They provide a simple way to have a single file for the logic and linked files for the model types.

When working with ASP.NET Core API Endpoints your project won't need any Controller classes. You can organize the Endpoints however you want. By feature. In a giant Endpoints folder. It doesn't matter - they'll work regardless of where you put them.

Most REST APIs have groups of endpoints for a given resource. In Controller-based projects you would have a controller per resource. When using API Endpoints you can simply create a folder per resource, just as you would use folders to group related pages in Razor Pages.

Instead of Model-View-Controller (MVC) the pattern becomes Request-EndPoint-Response(REPR). The REPR (reaper) pattern is much simpler and groups everything that has to do with a particular API endpoint together. It follows SOLID principles, in particular SRP and OCP. It also has all the benefits of feature folders and better follows the Common Closure Principle by grouping together things that change together.

3. Getting Started

Set Up an Empty Web API Project

Overview

When starting a new Web API project using .NET, you might want to begin with an empty project structure to have more control over dependencies and configurations.

Setting Up the Project

1. Create the Project:

   Start by creating a new empty web API project. You can do this using the .NET CLI:

   dotnet new web -n MyWebApi
   cd MyWebApi
   

   This creates a basic project structure for a web application.

2. Update Program.cs:

   Open the Program.cs file, which serves as the entry point for your application. By default, it might contain the following code:

   var builder = WebApplication.CreateBuilder(args);
   var app = builder.Build();
   
   // app.MapGet("/", () => "Hello World!");
   
   app.Run();
   

   Remove the app.MapGet("/", () => "Hello World!"); line as it sets up a minimal endpoint which we'll replace with controller routing.

3. Configure Services and Routing:

   Modify the Program.cs file to include controller services and routing:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add controllers
   builder.Services.AddControllers();
   
   var app = builder.Build();
   
   // Map controllers to endpoints
   app.MapControllers();
   
   app.Run();
   

   • builder.Services.AddControllers(): Adds services required for controllers to handle HTTP requests.
   • app.MapControllers(): Maps controllers to appropriate endpoints based on routing attributes and conventions.

   These two methods are required for the endpoint to work.

Adding Controllers with Ardalis.ApiEndpoints

1. Install Ardalis.ApiEndpoints NuGet Package

   Add the Ardalis.ApiEndpoints package to your ASP.NET Core web project. You can do this using the NuGet Package Manager or via the .NET CLI:

   dotnet add package Ardalis.ApiEndpoints
   

2. Create Endpoint Classes

   Create your endpoint classes by inheriting from EndpointBaseSync or EndpointBaseAsync, and add .WithRequest<TRequest> or .WithResult<TResponse>, or both, depending on whether your endpoint accepts input (POST) or simply returns a response (GET).

3. Implement Handle Method

   Implement the Handle method from the base class (EndpointBaseSync) in your endpoint class. This method contains the logic to process the request and return the response.

   public class MyEndpoint : EndpointBaseSync
    .WithRequest<string>
    .WithActionResult<IActionResult>
    {
        [HttpGet("my-endpoint")]
        public override ActionResult<IActionResult> Handle(string request)
        {
            // Your logic here
   
            return Ok();
        }
    }
   

4. Add Routing Attributes

   Decorate your Handle method with [HttpGet], [HttpPost], or other appropriate HTTP method attributes, specifying the route for your endpoint.

5. Define Request and Response Types

   Define your TRequest and TResponse types in the same file as your endpoint class or in separate files as per your project structure.

6. Test Your API Endpoint

   Test your ASP.NET Core API endpoint. If you're using Swagger/OpenAPI, it should automatically document your endpoint based on the attributes provided.

Example Endpoint Class

Here's an example of a GET endpoint that returns a list of books using Ardalis.ApiEndpoints:

…

This endpoint demonstrates listing books and uses the HttpGet annotation.

Adding common endpoint groupings using Swagger

In a standard Web API controller, methods in the same class are grouped together in the Swagger UI. To add this same functionality for endpoints:

1. Install the Swashbuckle.AspNetCore.Annotations

dotnet add package Swashbuckle.AspNetCore.Annotations

1. Add EnableAnnotations to the Swagger configura