Endpoints (AspNetCore)

About

Arcturus.AspNetCore.Endpoints enables a builder pattern for API endpoints, rather than conventional ASP.Net Core MVC. Two conventions are included in the package. The EndpointsBuilder convention and the IEndPointModule convention.

Installation

dotnet add package Arcturus.AspNetCore.Endpoints

Endpoint convention

By leveraging the EndpointsBuilder, you construct the API endpoint using a builder pattern, with finally implements the abstract class for implementation.

Example:

using Arcturus.AspNetCore.Endpoints;
using Microsoft.AspNetCore.Mvc;

namespace CodeSample.Endpoints.Weather;

public class GetWeatherEndpoint : EndpointsBuilder
    .WithRequest<GetWeatherEndpoint.GetWeatherRequest>
    .WithActionResultAsync
{
    [HttpGet("")]
    [Tags("Weather")]
    public override Task<IActionResult> HandleAsync(
        GetWeatherRequest request
        , CancellationToken cancellationToken = default)
    {
        throw new NotImplementedException();
    }

    public class GetWeatherRequest
    {
        [FromHeader]
        public required string MyHeader { get; init; }
        [FromQuery]
        public string? MyQuery { get; init; }

    }
}

If you use the default naming of endpoints as Get(Nuon)Endpoint, you can use the Endpoint convention as follows.

The Endpoint convention removed any Endpoint prefix and removes any of the following prefix's (Get|List|Create|Post|Delete|Update|Patch). This simplfies naming of the endpoint, specific when dealing with OpenAPI and Swaggger.

using Arcturus.AspNetCore.Endpoints;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers(con => con.UseEndpointsConventions());

var app = builder.Build();

// Ensure the mapping exists
app.MapControllers();

FAQ

Use multiple binding parameters

If you wish to use parameters from-query, from-header, from-body, please decorate the request class with the required bindings.

// use binding on the request class
public class GetWeatherRequest
{
  [FromHeader]
  public required string MyHeader { get; init; }
  [FromQuery]
  public string? MyQuery { get; init; }
}

Endpoint module convention

The endpoint module convention is more configurable, allowing an endpoint module itself register and handle mapping. This is exemplified as below, using the all familiar minimal API approach. The concept of the endpoint module approach allows to isolate handling, registration and coupling of the endpoint in one file.

public class SampleEndpoint : IEndPointModule
{
    public void AddRoute(IEndpointRouteBuilder app)
    {
        app
            .MapGet("/sample", () => HandleRequest)
            .RequireAuthorization();
    }

    private string HandleRequest()
    {
        return "Hello, world!";
    }
}

Register all endpoint module using the following in Program.cs

using Arcturus.AspNetCore.Endpoints;

var builder = WebApplication.CreateBuilder(args);

// Add endpoints to the container.
builder.Services.AddEndpointModules();

var app = builder.Build();

// Ensure the mapping exists
app.MapEndpointModules();