CleanCodeJN.GenericApis 3.3.0

Generic Web Apis

CRUD support for WebAPIs with the power of Mediator pattern, Automapper with automatic mapping, DataRepositories and Entity Framework

This CleanCodeJN package streamlines the development of web APIs in .NET applications by providing a robust framework for CRUD operations and facilitating the implementation of complex business logic in a clean and maintainable manner.

Features

• Paginated and filtered CRUD APIs (Minimal or Controller based) build in seconds
• Uses Mediator to abstract build-in and custom complex business logic
• Uses DataRepositories to abstract Entity Framework from business logic
• Enforces IOSP (Integration/Operation Segregation Principle) for commands
• Easy to mock and test
• Automatic Entity to DTO mapping (no mapping config needed)
• Built-in support for Fluent Validation
• On latest .NET 8.0

How to use

• Add RegisterRepositoriesCommandsWithAutomaticMapping<IDataContext>() to your Program.cs
• Add app.RegisterApis() to your Program.cs or use AddControllers + MapControllers()
• Start writing Apis by implementing IApi
• Extend standard CRUD operations by specific Where() and Include() clauses
• Use IOSP for complex business logic

Step by step explanation

Add RegisterRepositoriesCommandsWithAutomaticMapping<IDataContext>() to your Program.cs

// All Entity <=> DTO Mappings will be done automatically if the naming Convention will be applied:
// e.g.: Customer <=> CustomerGetDto 
// DTO has to start with Entity-Name and must inherits from IDto
// Entity must inherit from IEntity
builder.Services.RegisterRepositoriesCommandsWithAutomaticMapping<MyDbContext>();

You can also override specific mappings in RegisterRepositoriesCommandsWithAutomaticMapping<IDataContext>() in your Program.cs

// All other automatic mappings will be persisted
builder.Services.RegisterRepositoriesCommandsWithAutomaticMapping<MyDbContext>(cfg =>
{
    cfg.CreateMap<Customer, CustomerGetDto>()
       .ForMember(x => x.Name, opt => opt.MapFrom(x => string.Join(", ", x.Invoices.Select(x => x.Id))))
       .ReverseMap();
});

Add app.RegisterApis() when using Minimal APIs to your Program.cs

app.RegisterApis();

When using Controllers add this to your Program.cs

builder.Services.AddControllers();

// After Build()
app.MapControllers();

Start writing Minimal Apis by implementing IApi

public class CustomersV1Api : IApi
{
    public List<string> Tags => ["Customers Minimal API"];

    public string Route => $"api/v1/Customers";

    public List<Func<WebApplication, RouteHandlerBuilder>> HttpMethods =>
    [
         app => app.MapGet<Customer, CustomerGetDto, int>(Route, Tags,
            where: x => x.Name.StartsWith("a"), includes: [x => x.Invoices], asNoTracking: false),
        app => app.MapGetPaged<Customer, CustomerGetDto, int>(Route, Tags),
        app => app.MapGetFiltered<Customer, CustomerGetDto, int>(Route, Tags),
        app => app.MapGetById<Customer, CustomerGetDto, int>(Route, Tags),
        app => app.MapPut<Customer, CustomerPutDto, CustomerGetDto>(Route, Tags),
        app => app.MapPost<Customer, CustomerPostDto, CustomerGetDto>(Route, Tags),

        // Or use a custom Command with MapRequest
        app => app.MapDeleteRequest(Route, Tags, async (int id, [FromServices] ApiBase api) =>
                await api.Handle<Customer, CustomerGetDto>(new SpecificDeleteRequest { Id = id }))
    ];
}

Extend standard CRUD operations by specific Where() and Include() clauses

public class CustomersV1Api : IApi
{
    public List<string> Tags => ["Customers Minimal API"];

    public string Route => $"api/v1/Customers";

    public List<Func<WebApplication, RouteHandlerBuilder>> HttpMethods =>
    [
         app => app.MapGet<Customer, CustomerGetDto, int>(Route, Tags, where: x => x.Name.StartsWith("a")),
    ];
}

Or use ApiCrudControllerBase for CRUD operations in controllers

[Tags("Customers Controller based")]
[Route($"api/v2/[controller]")]

public class CustomersController(IMediator commandBus, IMapper mapper)
    : ApiCrudControllerBase<Customer, CustomerGetDto, CustomerPostDto, CustomerPutDto, int>(commandBus, mapper)
{
}

You can also override your Where and Include clauses

[Tags("Customers Controller based")]
[Route($"api/v2/[controller]")]

public class CustomersController(IMediator commandBus, IMapper mapper)
    : ApiCrudControllerBase<Customer, CustomerGetDto, CustomerPostDto, CustomerPutDto, int>(commandBus, mapper)
{
    public override Expression<Func<Customer, bool>> GetWhere => x => x.Name.StartsWith("a");

    public override List<Expression<Func<Customer, object>>> GetIncludes => [x => x.Invoices];
}

For using the /filtered api with a filter, just provide a serialized json as filter parameter, like this:

{
    "Filters": [
        {
            "Field": "Name",
            "Value": "aac",
            "Type": 0
        },
        {
            "Field": "Id",
            "Value": "3",
            "Type": 1
        }
    ]
}

Which means: Give me all Names which CONTAINS "aac" AND have Id EQUALS 3. So string Types use always CONTAINS and integer types use EQUALS. All filters are combined with ANDs.

The Type can be specified with these values:

public enum FilterTypeEnum
{
    STRING = 0,
    INTEGER = 1,
    DOUBLE = 2,
    INTEGER_NULLABLE = 3,
    DOUBLE_NULLABLE = 4,
    DATETIME = 5,
    DATETIME_NULLABLE = 6,
    GUID = 7,
    GUID_NULLABLE = 8,
}

More Advanced Topics

Built-in Support for Fluent Validation:

Just write your AbstractValidators<T>. They will be automatically executed on generic POST and generic PUT actions:

public class CustomerPostDtoValidator : AbstractValidator<CustomerPostDto>
{
    public CustomerPostDtoValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MaximumLength(10);
    }

public class CustomerPutDtoValidator : AbstractValidator<CustomerPutDto>
{
    public CustomerPutDtoValidator()
    {
        RuleFor(x => x.Id)
            .GreaterThan(0);

        RuleFor(x => x.Name)
            .NotEmpty()
            .MaximumLength(10)
            .CreditCard();
    }
}

Implement your own specific Request:

public class SpecificDeleteRequest : IRequest<BaseResponse<Customer>>
{
    public required int Id { get; init; }
}

With your own specific Command using CleanCodeJN.Repository

public class SpecificDeleteCommand(IRepository<Customer, int> repository) : IRequestHandler<SpecificDeleteRequest, BaseResponse<Customer>>
{
    public async Task<BaseResponse<Customer>> Handle(SpecificDeleteRequest request, CancellationToken cancellationToken)
    {
        var deletedCustomer = await repository.Delete(request.Id, cancellationToken);

        return await BaseResponse<Customer>.Create(deletedCustomer is not null, deletedCustomer);
    }
}

Use IOSP for complex business logic

Derive from BaseIntegrationCommand:

public class YourIntegrationCommand(ICommandExecutionContext executionContext)
    : BaseIntegrationCommand(executionContext), IRequestHandler<YourIntegrationRequest, BaseResponse>

Write Extensions on ICommandExecutionContext with Built in Requests or with your own

public static ICommandExecutionContext CustomerGetByIdRequest(
    this ICommandExecutionContext executionContext, int customerId) 
    => executionContext.WithRequest(
            () => new GetByIdRequest<Customer>
            {
                Id = customerId,
                Includes = [x => x.Invoices, x => x.OtherDependentTable],
            },
            CommandConstants.CustomerGetById);

See the how clean your code will look like in the end

public class YourIntegrationCommand(ICommandExecutionContext executionContext)
    : BaseIntegrationCommand(executionContext), IRequestHandler<YourIntegrationRequest, BaseResponse<Customer>>
{
    public async Task<BaseResponse<Customer>> Handle(YourIntegrationRequest request, CancellationToken cancellationToken) =>
        await ExecutionContext
            .CandidateGetByIdRequest(request.Dto.CandidateId)
            .CustomerGetByIdRequest(request.Dto.CustomerIds)
            .GetOtherStuffRequest(request.Dto.XYZType)
            .PostSomethingRequest(request.Dto)
            .SendMailRequest()
            .Execute<Customer>(cancellationToken);
}

Sample Code

GitHub Full Sample