The REPR (Request-Endpoint-Response) pattern is a modern architectural approach for building ASP.NET Core APIs that promotes clean, maintainable, and testable code. Unlike traditional controller-based architectures, REPR organizes your API around individual endpoint classes, each representing a single operation.
- Single Responsibility Principle: Each endpoint class handles exactly one operation, making your code more focused and easier to understand.
- Better Testability: Individual endpoints can be unit tested in isolation without the complexity of controller dependencies.
- Improved Organization: Related logic is contained within a single class, reducing the cognitive load when working with complex APIs.
- Enhanced Maintainability: Changes to one endpoint don't affect others, reducing the risk of introducing bugs.
- Cleaner Dependency Injection: Each endpoint can have its own specific dependencies without bloating a shared controller.
- Type Safety: Strong typing for requests and responses with compile-time validation.
Add the ReprEndpoint library to your project:
<PackageReference Include="ReprEndpoint" Version="1.0.1" />Or visit the NuGet package page: https://www.nuget.org/packages/ReprEndpoint
You can also install it via the Visual Studio Package Manager UI by searching for "ReprEndpoint".
Configure your ASP.NET Core application to use ReprEndpoint:
using TheReprEndpoint;
var builder = WebApplication.CreateBuilder(args);
// Register all endpoints from the current assembly
builder.Services.AddReprEndpoints();
// Add other services
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
// Configure middleware
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
// Map all registered endpoints
app.MapReprEndpoints();
app.Run();The ReprEndpoint library provides four base classes to suit different endpoint scenarios:
Use this when your endpoint needs both a strongly-typed request and response:
public class CreateUserEndpoint : ReprEndpoint<CreateUserRequest, UserResponse>
{
private readonly IUserService _userService;
public CreateUserEndpoint(IUserService userService)
{
_userService = userService;
}
public override async Task<UserResponse> HandleAsync(CreateUserRequest request, CancellationToken ct = default)
{
var user = await _userService.CreateUserAsync(request.Name, request.Email, ct);
return new UserResponse
{
Id = user.Id,
Name = user.Name,
Email = user.Email
};
}
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
MapPost(routes, "/users")
.WithName("CreateUser")
.WithOpenApi();
}
}
public record CreateUserRequest(string Name, string Email);
public record UserResponse(int Id, string Name, string Email);Use this when you need a strongly-typed request but want to return an IResult for flexible response handling:
public class UpdateUserEndpoint : ReprRequestEndpoint<UpdateUserRequest>
{
private readonly IUserService _userService;
public UpdateUserEndpoint(IUserService userService)
{
_userService = userService;
}
public override async Task<IResult> HandleAsync(UpdateUserRequest request, CancellationToken ct = default)
{
var user = await _userService.GetUserAsync(request.Id, ct);
if (user == null)
return Results.NotFound($"User with ID {request.Id} not found");
await _userService.UpdateUserAsync(request.Id, request.Name, request.Email, ct);
return Results.NoContent();
}
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
MapPut(routes, "/users/{id}")
.WithName("UpdateUser")
.WithOpenApi();
}
}
public record UpdateUserRequest(int Id, string Name, string Email);Use this for endpoints that don't require input parameters but return a strongly-typed response:
public class GetAllUsersEndpoint : ReprResponseEndpoint<List<UserResponse>>
{
private readonly IUserService _userService;
public GetAllUsersEndpoint(IUserService userService)
{
_userService = userService;
}
public override async Task<List<UserResponse>> HandleAsync(CancellationToken ct = default)
{
var users = await _userService.GetAllUsersAsync(ct);
return users.Select(u => new UserResponse(u.Id, u.Name, u.Email)).ToList();
}
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
MapGet(routes, "/users")
.WithName("GetAllUsers")
.WithOpenApi();
}
}Use this for simple endpoints that don't need strongly-typed requests or responses:
public class HealthCheckEndpoint : ReprEndpoint
{
private readonly ILogger<HealthCheckEndpoint> _logger;
public HealthCheckEndpoint(ILogger<HealthCheckEndpoint> logger)
{
_logger = logger;
}
public override Task<IResult> HandleAsync(CancellationToken ct = default)
{
_logger.LogInformation("Health check requested");
return Task.FromResult(Results.Ok(new { Status = "Healthy", Timestamp = DateTime.UtcNow }));
}
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
MapGet(routes, "/health")
.WithName("HealthCheck")
.WithOpenApi();
}
}By default, requests are bound from the request body (typically JSON):
public class CreateProductEndpoint : ReprEndpoint<CreateProductRequest, ProductResponse>
{
// RequestAsParameters is false by default
public override bool RequestAsParameters => false;
public override async Task<ProductResponse> HandleAsync(CreateProductRequest request, CancellationToken ct)
{
// request is bound from JSON body
// POST /products
// Body: { "name": "Laptop", "price": 999.99 }
}
}Override RequestAsParameters to bind from query string, route values, or form data:
public class GetUserEndpoint : ReprEndpoint<GetUserRequest, UserResponse>
{
//Apply [AsParameters] on your request.
public override bool RequestAsParameters => true;
public override async Task<UserResponse> HandleAsync(GetUserRequest request, CancellationToken ct)
{
// request is bound from route and query parameters
// GET /users/123?includeDetails=true
}
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
MapGet(routes, "/users/{id}")
.WithName("GetUser")
.WithOpenApi();
}
}
public record GetUserRequest(int Id, bool IncludeDetails = false);Group related endpoints under a common prefix:
public class GetUserProfileEndpoint : ReprResponseEndpoint<UserProfile>
{
public override string? GroupPrefix => "/api/v1/users";
public override Action<RouteGroupBuilder>? ConfigureGroup => group =>
{
group.RequireAuthorization()
.WithTags("Users")
.WithOpenApi();
};
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
MapGet(routes, "/{id}/profile")
.WithName("GetUserProfile");
}
}This creates the endpoint at /api/v1/users/{id}/profile with authorization requirements.
public class AdminUserEndpoint : ReprEndpoint<AdminRequest, AdminResponse>
{
public override string? GroupPrefix => "/api/admin";
public override Action<RouteGroupBuilder>? ConfigureGroup => group =>
{
group.RequireAuthorization("AdminPolicy")
.AddEndpointFilter<AdminLoggingFilter>()
.WithTags("Administration")
.WithOpenApi();
};
}The library integrates seamlessly with ASP.NET Core API versioning:
public class GetWeatherForecastV1Endpoint : ReprResponseEndpoint<WeatherForecast[]>
{
private static readonly string[] Summaries =
[
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
];
private readonly ILogger<GetWeatherForecastV1Endpoint> _logger;
public GetWeatherForecastV1Endpoint(ILogger<GetWeatherForecastV1Endpoint> logger)
{
_logger = logger;
}
public override Task<WeatherForecast[]> HandleAsync(CancellationToken ct = default)
{
_logger.LogInformation("Generating weather forecast for 5 days (V1)");
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
{
Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
return Task.FromResult(forecast);
}
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
var versionSet = routes.NewApiVersionSet()
.HasApiVersion(new ApiVersion(1, 0))
.Build();
MapGet(routes, "/v{version:apiVersion}/weatherforecast")
.WithName("GetWeatherForecastV1")
.WithApiVersionSet(versionSet)
.WithOpenApi();
}
}
public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ApiVersionReader = ApiVersionReader.Combine(
new QueryStringApiVersionReader("version"),
new HeaderApiVersionReader("X-Version"),
new UrlSegmentApiVersionReader()
);
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});Register all endpoints from assemblies:
// Register from current assembly with default lifetime (Transient)
builder.Services.AddReprEndpoints();
// Register from specific assemblies
builder.Services.AddReprEndpoints(ServiceLifetime.Scoped, typeof(UserEndpoint).Assembly);
// Register specific endpoint types
builder.Services.AddReprEndpoints(ServiceLifetime.Singleton, typeof(HealthCheckEndpoint));Choose appropriate service lifetimes based on your needs:
- Transient (default): New instance for each request
- Scoped: One instance per HTTP request
- Singleton: Single instance for the application lifetime
Inject services into your endpoints:
public class ProcessOrderEndpoint : ReprEndpoint<ProcessOrderRequest, OrderResult>
{
private readonly IOrderService _orderService;
private readonly IPaymentService _paymentService;
private readonly IInventoryService _inventoryService;
private readonly ILogger<ProcessOrderEndpoint> _logger;
public ProcessOrderEndpoint(
IOrderService orderService,
IPaymentService paymentService,
IInventoryService inventoryService,
ILogger<ProcessOrderEndpoint> logger)
{
_orderService = orderService;
_paymentService = paymentService;
_inventoryService = inventoryService;
_logger = logger;
}
public override async Task<OrderResult> HandleAsync(ProcessOrderRequest request, CancellationToken ct)
{
_logger.LogInformation("Processing order {OrderId}", request.OrderId);
// Check inventory
var available = await _inventoryService.CheckAvailabilityAsync(request.Items, ct);
if (!available)
throw new InvalidOperationException("Insufficient inventory");
// Process payment
var paymentResult = await _paymentService.ProcessPaymentAsync(request.Payment, ct);
if (!paymentResult.Success)
throw new InvalidOperationException("Payment failed");
// Create order
var order = await _orderService.CreateOrderAsync(request, ct);
_logger.LogInformation("Order {OrderId} processed successfully", order.Id);
return new OrderResult(order.Id, order.Status, order.Total);
}
public override void MapEndpoint(IEndpointRouteBuilder routes)
{
MapPost(routes, "/orders/process")
.WithName("ProcessOrder")
.RequireAuthorization()
.WithOpenApi();
}
}We welcome contributions to make ReprEndpoint even better! Here are some ways you can help:
Your star helps others discover this library and motivates continued development.
We're open to pull requests!
Please feel free to fork the repository and submit a pull request. For larger changes, consider opening an issue first to discuss your approach.
Found a bug or have a suggestion? Please open an issue with:
- A clear description of the problem or enhancement
- Steps to reproduce (for bugs)
- Sample code demonstrating the issue
- Expected vs actual behavior