CG.Infrastructure.Endpoints 3.10.7

CG.Infrastructure.Endpoints

A .NET library that provides a clean, organized approach to managing API endpoints in ASP.NET Core applications with built-in API versioning support.

Features

• Endpoint Management: Organized endpoint registration and mapping using interfaces
• API Versioning: Built-in support for ASP.NET Core API versioning
• Automatic Discovery: Automatic discovery and registration of endpoints
• Route Grouping: Support for both grouped and root-level endpoints
• Dependency Injection: Seamless integration with .NET dependency injection
• Type Safety: Strongly-typed endpoint interfaces

Requirements

• .NET 9.0 or later
• ASP.NET Core 9.0 or later
• CG.Infrastructure.Core package

Installation

dotnet add package CG.Infrastructure.Endpoints

Quick Start

1. Register Services

using Infrastructure.Endpoints.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register API versioning
builder.Services.RegisterApiVersioning(majorVersion: 1, minorVersion: 0);

// Register endpoints
builder.Services.RegisterEndpoints();
builder.Services.RegisterRootEndpoints();

2. Create Endpoints

Implement the IEndpoint interface for grouped endpoints:

public class UserEndpoints : IEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/users")
            .WithApiVersionSet(ApiVersioning.VersionSet)
            .MapToApiVersion(new ApiVersion(1, 0));

        group.MapGet("/", GetUsers);
        group.MapGet("/{id}", GetUser);
        group.MapPost("/", CreateUser);
        group.MapPut("/{id}", UpdateUser);
        group.MapDelete("/{id}", DeleteUser);
    }

    private static async Task<IResult> GetUsers() => Results.Ok("Users list");
    private static async Task<IResult> GetUser(int id) => Results.Ok($"User {id}");
    private static async Task<IResult> CreateUser() => Results.Created();
    private static async Task<IResult> UpdateUser(int id) => Results.Ok($"Updated {id}");
    private static async Task<IResult> DeleteUser(int id) => Results.Ok($"Deleted {id}");
}

Implement the IRootEndpoint interface for root-level endpoints:

public class HealthEndpoints : IRootEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app)
    {
        app.MapGet("/health", () => Results.Ok("Healthy"));
        app.MapGet("/ready", () => Results.Ok("Ready"));
    }
}

3. Map Endpoints

var app = builder.Build();

// Map grouped endpoints
app.MapEndpoints(app.MapGroup("/api"));

// Map root endpoints
app.MapRootEndpoints();

Core Functionality

API Versioning

The library provides a clean way to configure API versioning:

builder.Services.RegisterApiVersioning(
    majorVersion: 1, 
    minorVersion: 0, 
    status: "alpha"
);

This configures:

• Default API version
• Automatic version assumption
• API version reporting
• URL substitution for versioning

Endpoint Registration

Two types of endpoint registration are supported:

Grouped Endpoints (IEndpoint)

• Automatically discovered and registered
• Mapped within route groups
• Ideal for feature-based API organization

Root Endpoints (IRootEndpoint)

• Automatically discovered and registered
• Mapped at the application root level
• Perfect for health checks, status endpoints, etc.

Automatic Discovery

The library automatically discovers and registers endpoints by scanning the calling assembly for types that implement IEndpoint or IRootEndpoint.

Configuration Options

API Versioning Options

builder.Services.RegisterApiVersioning(
    majorVersion: 1,        // Major version number
    minorVersion: 0,        // Minor version number
    status: "beta"          // Optional status (alpha, beta, rc, etc.)
);

Endpoint Mapping

// Map grouped endpoints with custom route group
app.MapEndpoints(app.MapGroup("/api/v1"));

// Map root endpoints
app.MapRootEndpoints();

Dependencies

• Asp.Versioning.Http: API versioning support
• Asp.Versioning.Mvc.ApiExplorer: API explorer integration
• CG.Infrastructure.Core: Core infrastructure functionality
• Microsoft.Extensions.DependencyInjection.Abstractions: DI abstractions

Integration

With Minimal APIs

var builder = WebApplication.CreateBuilder(args);

// Register services
builder.Services.RegisterApiVersioning(1, 0);
builder.Services.RegisterEndpoints();
builder.Services.RegisterRootEndpoints();

var app = builder.Build();

// Map endpoints
app.MapEndpoints(app.MapGroup("/api"));
app.MapRootEndpoints();

app.Run();

With Controllers

The library works seamlessly with traditional controller-based APIs and can be used alongside them.

Best Practices

1. Organize by Feature: Group related endpoints using the IEndpoint interface
2. Use Root Endpoints Sparingly: Reserve IRootEndpoint for application-wide concerns
3. Version Consistently: Use the same versioning strategy across all endpoints
4. Follow Naming Conventions: Use descriptive names for endpoint classes
5. Keep Endpoints Focused: Each endpoint class should handle a specific domain or feature

Examples

Complete API Setup

var builder = WebApplication.CreateBuilder(args);

// Configure services
builder.Services.RegisterApiVersioning(1, 0);
builder.Services.RegisterEndpoints();
builder.Services.RegisterRootEndpoints();

// Add other services
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure middleware
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();

// Map endpoints
app.MapControllers();
app.MapEndpoints(app.MapGroup("/api"));
app.MapRootEndpoints();

app.Run();

Feature-Based Organization

// User management endpoints
public class UserEndpoints : IEndpoint { ... }

// Product catalog endpoints
public class ProductEndpoints : IEndpoint { ... }

// Order management endpoints
public class OrderEndpoints : IEndpoint { ... }

// System health endpoints
public class HealthEndpoints : IRootEndpoint { ... }

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Version History

• 3.10.4: Current version with .NET 9.0 support
• 3.10.0: Initial release with basic endpoint management

Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Review the examples in this README

Related Packages

• CG.Infrastructure.Core: Core infrastructure functionality
• CG.Infrastructure.Configuration: Configuration management
• CG.Infrastructure.Data: Data access and database operations
• CG.Infrastructure.Calendar: Calendar and time management