# Ardalis.ApiEndpoints: one class per endpoint for ASP.NET Core

> Ardalis.ApiEndpoints replaces MVC controllers with a single class per route, using fluent generics over ASP.NET Core. The README now points new .NET 6+ projects at Minimal APIs and FastEndpoints instead, which shapes who should still adopt it.

**ardalis/ApiEndpoints** — A project for supporting API Endpoints in ASP.NET Core web applications.

- Repository: https://github.com/ardalis/ApiEndpoints
- Stars: 3,198 · Forks: 231
- Language: C#
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/ardalis-apiendpoints

## The controller cohesion problem this library attacks

The README opens with an argument rather than a feature list: MVC controllers are described as collections of methods that never call one another and rarely operate on the same state. The claim is that a controller is not cohesive, that its private methods are usually called by exactly one public method, and that it grows without bound because it is the only option shipped out of the box. Whether or not you accept the framing, the practical complaint is familiar to anyone who has opened a 900-line controller to change one action.

The library's answer is to make the endpoint the unit of code. Instead of a controller class holding several actions, you write one class per route, and that class is the handler. The README ties this to the REPR pattern (Request-Endpoint-Response), which it links to on deviq.com. The intended audience is therefore an ASP.NET Core team already on controllers that wants per-route organization without introducing a mediator: the README explicitly asks "what if you didn't even need that extra plumbing?" and positions MediatR as the workaround this library makes unnecessary. If your API is small, or your team is happy with fat controllers, the problem this solves may not be a problem you have.

## How the fluent generic base classes actually constrain an endpoint

The mechanism is inheritance plus generic type parameters. An endpoint class derives from a base such as EndpointBaseSync or EndpointBaseAsync, then chains .WithRequest<T> and either .WithResult<T> or .WithActionResult<T> to declare what comes in and what goes out. The base class supplies the controller behaviour; your class supplies a Handle method.

v4 changed the vocabulary, and the distinction is worth stating precisely because it trips up upgrades. The result is the return type of Handle. The response is the data or DTO carried inside that result. ASP.NET Core MVC calls these ActionResults, so the package renamed WithResponse to WithResult or WithActionResult to match. The README's migration advice is mechanical: replace WithResponse<T> with WithActionResult<T> to keep v3 behaviour, or use something like WithResult<FileResult> when you need a different result type. The second v4 change is the base class rename, BaseEndpoint to EndpointBaseSync and BaseAsyncEndpoint to EndpointBaseAsync, which the README says typically requires no change to the Handle method itself.

There is an escape hatch. You can inherit from EndpointBase directly, without the .With* additions, which the README describes as giving you a controller with a single Handle method and no restrictions on parameter count or type. That is the honest admission that the fluent generics only cover the common shapes; the moment your endpoint needs an unusual parameter list, you leave the typed path.

## Installing the package and writing a first endpoint

The package is published on NuGet as Ardalis.ApiEndpoints, which is the source the README badges point at. Installation is a package reference in a project that already targets ASP.NET Core.

```bash
dotnet add package Ardalis.ApiEndpoints
```

The README's Getting Started section describes setting up an empty Web API project first, and the repository ships a worked example under sample/SampleEndpointApp plus a weather forecast sample under sample/Sample.WeatherForecast. The shape of a v4 endpoint, taken from the upgrade notes, is a class that inherits the sync base and declares its request and action result types.

```csharp
public class ForecastEndpoint : EndpointBaseSync
    .WithRequest<ForecastRequestDto>
    .WithActionResult<IEnumerable<WeatherForecast>>
{
    // Handle method implementation goes here
}
```

The README shows this as a diff against the v3 form, so the class definition is the part that changed; the notes state the Handle method usually does not. For async endpoints the same pattern applies with EndpointBaseAsync. After adding endpoints, the README's table of contents lists a section on adding common endpoint groupings using Swagger and a file upload example, both of which live in the longer guide rather than in the excerpt here.

One thing to note about versioning: the most recent release listed is v4.1.0 from 2023-06-01, while the repository's last push was 2026-03-09. The commit activity and the release cadence are not the same thing, so pin the package version you actually test against.

## The README recommends against this library for new projects

This is the limitation that matters most, and it comes from the maintainer rather than from a critic. The README's Fast Endpoints section states that if you are on .NET 6 or later, you are probably better off using Minimal APIs than Controllers, and it calls MVC a dull edge technology. It then says that if you like the organization this library provides and the REPR pattern in general, the author now recommends the FastEndpoints library instead, describing its core API endpoint functionality as very solid and fast.

That is an unusual position for a project's own README, and it should be read literally. The library still works and the repository is not archived, but the documented direction of travel points elsewhere. A team choosing it in 2026 for greenfield work is choosing against the maintainer's stated advice.

The v4 breaking changes are the second constraint. Fluent generics and base types were reworked, so any v3 codebase must rename base classes and replace WithResponse with WithActionResult. The README calls the updates straightforward, and the diff it provides is small, but the notes cover only the two main changes. There is no deprecation shim mentioned, and the README does not document rollback if the rename goes wrong in a large solution.

## FastEndpoints and Minimal APIs: the real difference in approach

FastEndpoints, which the README names directly, keeps the endpoint-per-class idea but builds it on Minimal APIs rather than on MVC controllers, and the README says it carries a lot of additional functionality you can use or not. That is the substantive difference: Ardalis.ApiEndpoints wraps the MVC pipeline, so you inherit MVC's result types and its conventions, while FastEndpoints starts from the newer, lighter hosting model. If you are on .NET 8, that foundation is the one Microsoft is investing in, and the README's own recommendation follows from it.

Minimal APIs are the other alternative, and they are not the same shape at all. A Minimal API endpoint is a lambda registered on the application builder, not a class. You get far less ceremony and no per-endpoint file unless you impose one yourself. The REPR organization that Ardalis.ApiEndpoints enforces through inheritance becomes a convention your team has to maintain by hand. For a handful of routes that is fine; for a large API where you want every endpoint to look identical, the class-based approach has an advantage Minimal APIs do not give you for free.

The honest summary is that Ardalis.ApiEndpoints sits between the two: more structure than Minimal APIs, less machinery than MediatR, and built on a pipeline the README itself describes as a dull edge.

## Maintenance, licensing and the cost of staying on v4

The repository is not archived and the last push was on 2026-03-09, so there is recent activity on the default branch. The release history is a different signal: v4.1.0 dates from 2023-06-01, and no later release appears in the list. Treat commit activity and package releases as separate facts when you plan an upgrade.

The licence is MIT, per the LICENSE.txt file at the repository root. That permits commercial use and modification, but it also means there is no support contract attached; issues are handled in the open source project on whatever schedule the maintainers keep. Nothing in the README describes a paid tier or commercial backing, so plan for community support only.

Upgrade cost is concentrated in the v3 to v4 rename. Because the change is a base class swap plus a WithResponse to WithActionResult substitution, the work scales with the number of endpoint classes in your solution rather than with their complexity. The README says the Handle method usually needs no change, which makes the migration mostly mechanical, but it also means a large codebase will produce a large diff for a small semantic change. If you are starting fresh on v4, you pay this cost once and never see it.

## Conclusion

Adopt Ardalis.ApiEndpoints if you have an existing MVC-based ASP.NET Core application and want each route in its own class without adding MediatR plumbing, or if you are working through the sample/SampleEndpointApp project to learn the REPR pattern. Do not adopt it for a new .NET 8 service: the README itself says you are probably better off with Minimal APIs, and it recommends FastEndpoints for the endpoint-per-class style. Before committing, verify two things in the repository: that your base classes reference EndpointBaseSync or EndpointBaseAsync rather than the v3 BaseEndpoint names, and that any WithResponse<T> usage has been rewritten as WithActionResult<T>, since v4 renamed both and the upgrade notes are the only migration path documented.

## FAQ

### What base class should an Ardalis.ApiEndpoints endpoint inherit in v4?

Synchronous endpoints inherit EndpointBaseSync and asynchronous ones inherit EndpointBaseAsync, replacing the v3 BaseEndpoint and BaseAsyncEndpoint names. You can also inherit EndpointBase directly if you need a Handle method without restrictions on parameter count or type.

### How do I install Ardalis.ApiEndpoints?

The package is published on NuGet as Ardalis.ApiEndpoints, so you add it as a package reference to an ASP.NET Core project. The README's Getting Started section describes setting up an empty Web API project before adding endpoints.

### Is Ardalis.ApiEndpoints still recommended for new ASP.NET Core projects?

The README says that on .NET 6 or later you are probably better off with Minimal APIs, and it recommends the FastEndpoints library for the endpoint-per-class organization. The library still works, but the maintainer's stated preference points elsewhere for new work.

## Sources

- [ardalis/ApiEndpoints on GitHub](https://github.com/ardalis/ApiEndpoints)
- [Issues](https://github.com/ardalis/ApiEndpoints/issues)
- [License: MIT](https://github.com/ardalis/ApiEndpoints/blob/main/LICENSE)
- [README](https://github.com/ardalis/ApiEndpoints/blob/main/README.md)
- [Releases](https://github.com/ardalis/ApiEndpoints/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ardalis-apiendpoints