EngageLabs.MinimalApi 1.2.0

MinimalApi

A way to pack minimal APIs into configurable modules.

Table of Contents

• MinimalApi
• Table of Contents
• Description
• Usage
  • Create your module
  • Register your module
  • Customize your module
• Sample code

Description

This project aims to provide a minimal API framework that allows you to easily configure and organize your API endpoints into modules. It provides a simple and lightweight solution for building APIs with minimal overhead.

Usage

Create your module

To define a new module, just create a class inheriting from ApiModule and provide a Prefix for your endpoints and a body for the RegisterEndpoints method.

REMEMBER: All modules are already prefixed with api/ when they are registered in the application.

using EngageLabs.MinimalApi;

public class MyModule : ApiModule
{
    public override string Prefix => "my-module";

    public override void RegisterEndpoints(IEndpointRouteBuilder app)
    {
        app.MapGet("", async (PostsRepository repository) =>
        {
            var posts = await repository.GetPostsAsync().ConfigureAwait(false);
            return Results.Ok(posts);
        });

        // ...
    }
}

Register your module

To register all of your modules, just call the MapApi() extension method in Program.cs.

using EngageLabs.MinimalApi;

var builder = WebApplication.CreateBuilder(args);

// Your service registrations

var app = builder.Build();

// Your middleware

app.MapApi(typeof(Program).Assembly); // <-- Register api modules

app.Run();

The MapApi() extension method accepts 2 parameters:

1. An assembly (or an array of assemblies) to scan and register all the modules and their related endpoints.

2. A configuration action to define the behavior of the entire API. This is a good spot, for example, to configure application-wide logic like authentication, rate limiting, etc.

Customize your module

If you need to define some behaviors common to all the endpoints of the module, you can override the Configure method of the ApiModule base class. You will be provided with an IEndpointConventionBuilder to define your conventions for the module.

The Configure method is a good spot, for example, to configure OpenAPI information like name, description, tags (also used in the Swagger page), etc., or some behaviors that differ from the application-wide ones defined in the global configuration.

using EngageLabs.MinimalApi;

public class MyModule : ApiModule
{
    // ... Other module code ...

    public override void Configure(IEndpointConventionBuilder group)
    {
        // Your conventions here
        group.RequireAuthorization()
            .RequireRateLimiting("fixed"); // "fixed" must be a policy name registered via AddRateLimiter

        group.WithName("My Module")
            .WithDescription("My awesome API module")
            .WithTags("API Module");
    }
}

NOTE: A single endpoint can opt out of a module-wide convention with AllowAnonymous(): if you configure your module with RequireAuthorization() but add .AllowAnonymous() to one or more MapGet() calls in RegisterEndpoints, those endpoints bypass authorization entirely, regardless of the group's configuration. This is different from stacking multiple RequireAuthorization() calls, which are combined with an AND instead of overriding each other. See showcase app readme for more info.

Sample code

See the showcase app readme for an overview of the showcase app with some examples.