Walfhand.QuickApi 1.0.5

QuickApi.Engine

Overview

QuickApi is a lightweight library designed to simplify the development of Minimal APIs in .NET applications. It provides seamless integration with popular CQRS tools like MediatR and Wolverine, enabling developers to quickly set up and scale their APIs with minimal boilerplate code.

Features

• Effortless Minimal API Setup: Simplifies configuration and reduces the boilerplate code.
• CQRS Integration: Built-in support for MediatR and Wolverine for handling commands, queries, and events.
• Developer Friendly: Focuses on improving productivity and code readability.
• NuGet Package: Easily installable via NuGet.

Installation

QuickApi is available on NuGet:

Install-Package Walfhand.QuickApi

Or, using the .NET CLI:

dotnet add package Walfhand.QuickApi

Getting Started

Step 1: Installation

Install the package using the .NET CLI:

dotnet add package Walfhand.QuickApi

Step 2: Register QuickApi in your Program.cs

Add the following lines to your Program.cs file:

builder.Services.AddMinimalEndpoints();
app.UseMinimalEndpoints();

Step 3: Implement the IMessage Interface

Implement the IMessage interface to use your preferred CQRS tool. Here is an example using MediatR:

using MediatR;
using QuickApi.Engine.Web.Cqrs;

namespace QuickApi.Example.Cqrs;

public class MessageService : IMessage
{
    private readonly IMediator _mediator;

    public MessageService(IMediator mediator)
    {
        _mediator = mediator;
    }

    public async Task<TResult> InvokeAsync<TResult>(object message, CancellationToken ct = default)
    {
        return await _mediator.Send((IRequest<TResult>)message, ct);
    }

    public async Task InvokeAsync(object message, CancellationToken ct = default)
    {
        await _mediator.Send(message, ct);
    }
}

Step 4: Register the Message Service

Register your MessageService implementation in the Program.cs file:

builder.Services.AddScoped<IMessage, MessageService>();

Step 5: Adding Endpoints

With QuickApi, you can define endpoints anywhere in your code by implementing one of the provided endpoint base classes.

Example: Adding a Todo Item without Policies

using MediatR;
using QuickApi.Engine.Web.Endpoints.Impl;
using QuickApi.Example.Features.Todos.Domain;

namespace QuickApi.Example.Features.Todos.AddTodo.Endpoints;

public record AddTodoRequest(string Title, string? Description) : IRequest<Todo>;

public class AddTodoEndpoint() : PostMinimalEndpoint<AddTodoRequest, Todo>("todos")
{
}

public class AddTodoRequestHandler : IRequestHandler<AddTodoRequest, Todo>
{
    public Task<Todo> Handle(AddTodoRequest request, CancellationToken cancellationToken)
    {
        // Example logic for creating a Todo item
        var todo = new Todo { Title = request.Title, Description = request.Description };
        return Task.FromResult(todo);
    }
}

Example: Adding a Todo Item with Policies

using MediatR;
using QuickApi.Engine.Web.Endpoints.Impl;
using QuickApi.Example.Features.Todos.Domain;

namespace QuickApi.Example.Features.Todos.AddTodo.Endpoints;

public record AddTodoRequest(string Title, string? Description) : IRequest<Todo>;

public class AddTodoEndpoint() : PostMinimalEndpoint<AddTodoRequest, Todo>(
    "todos", 
    nameof(PoliciesEnum.Subscribed))
{
}

public class AddTodoRequestHandler : IRequestHandler<AddTodoRequest, Todo>
{
    public Task<Todo> Handle(AddTodoRequest request, CancellationToken cancellationToken)
    {
        // Example logic for creating a Todo item
        var todo = new Todo { Title = request.Title, Description = request.Description };
        return Task.FromResult(todo);
    }
}

public class PoliciesEnum
{
    public const string Subscribed = "Subscribed";
}

Example: Customizing an Endpoint without MediatR

You can bypass the IMessage interface and MediatR by customizing your endpoint directly:

public class FilterTodoEndpointCustom() : FilterMinimalEndpoint<FilterTodoRequest, Todo>("todos/custom")
{
    protected override RouteHandlerBuilder Configure(IEndpointRouteBuilder builder)
    {
        //call base configure and get routeHandlerBuilder
        var routeHandlerBuilder = base.Configure(builder);
        
        //add your customization
        routeHandlerBuilder.ProducesProblem(500);
        
        //return routeHandlerBuilder custom
        return routeHandlerBuilder;
    }

    protected override Delegate Handler => EndpointHandler;

    private static async Task<IResult> EndpointHandler([AsParameters] FilterTodoRequest request, IDbContext context, CancellationToken ct)
    {
        var query = context.Set<Todo>().AsQueryable();
        if(request.IsCompleted.HasValue)
            query = query.Where(x => x.IsCompleted == request.IsCompleted);
        return Results.Ok(await query.ToListAsync(ct));
    }
}

Available Endpoint Base Classes

QuickApi provides several base classes to simplify the creation of endpoints:

• PostMinimalEndpoint: For POST requests.
• GetMinimalEndpoint: For GET requests.
• PutMinimalEndpoint: For PUT requests.
• DeleteMinimalEndpoint: For DELETE requests.
• PatchMinimalEndpoint: For PATCH requests.
• FilterMinimalEndpoint: For filtered GET requests.
• FilterPaginateMinimalEndpoint: For paginated and filtered GET requests.
• GetFileMinimalEndpoint: For serving files.

Example Project

A fully working example project is available. You can clone it and start it with the following command:

docker compose up --build

The application will be accessible at https://api.localhost/scalar/v1, where you can test more advanced features.

Note

When inheriting from a class like PostMinimalEndpoint, you can add security policies to your endpoint by passing them as a params array in the constructor after the route.

Packages will follow to simplify this integration for tools like MediatR and Wolverine.

Contributing

Contributions are welcome! If you find an issue or have an idea for improvement, feel free to submit a pull request or open an issue on the GitHub repository.