Nemeia.Api.Core 1.0.0

Nemeia.Api.Core

Modern API foundation package for ASP.NET Core applications.

Built to provide:

• Clean Architecture support
• Enterprise API standards
• OpenAPI integration
• Scalar integration
• JWT authentication
• Middleware pipeline
• CorrelationId tracing
• HealthChecks
• Standardized controllers
• Centralized exception handling

Features

✅ JWT Authentication
✅ Scalar OpenAPI UI
✅ OpenAPI integration
✅ Middleware pipeline
✅ CorrelationId support
✅ Global exception handling
✅ Request logging
✅ HealthChecks
✅ MainController base
✅ Standardized API responses
✅ Clean Architecture ready
✅ Microservice ready
✅ .NET 10 ready

Installation

dotnet add package Nemeia.Api.Core

Dependencies

Main dependencies used internally:

• Microsoft.AspNetCore.OpenApi
• Scalar.AspNetCore
• Microsoft.AspNetCore.Authentication.JwtBearer

Package Structure

Nemeia.Api.Core
│
├── Authentication
│   ├── Jwt
│   └── Extensions
│
├── Controllers
│
├── Extensions
│
├── HealthChecks
│   ├── Checks
│   ├── Extensions
│   └── Responses
│
├── Middleware
│
├── OpenApi
│   ├── Extensions
│   ├── Options
│   ├── Responses
│   └── Security
│
└── Responses

Quick Start

Program.cs

using Nemeia.Api.Core.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddNemeiaApiCore(
    builder.Configuration,
    "Meu Soro API");

builder.Services.AddNemeiaScalar(options =>
{
    options.Title = "Meu Soro API";
    options.Theme = "purple";
});

var app = builder.Build();

app.UseNemeiaApiCore();

app.MapControllers();

app.Run();

JWT Authentication

appsettings.json

{
  "Jwt": {
    "Issuer": "MeuSoro.Api",
    "Audience": "MeuSoro.Client",
    "SecretKey": "SUPER_SECRET_KEY_123456789"
  }
}

JWT Registration

builder.Services.AddNemeiaJwt(
    builder.Configuration);

Scalar OpenAPI

Enable Scalar

builder.Services.AddNemeiaScalar(options =>
{
    options.Title = "Meu Soro API";
    options.Theme = "mars";
});

OpenAPI Registration

builder.Services.AddNemeiaOpenApi(
    "Meu Soro API");

Middleware Pipeline

Automatically registers:

• CorrelationMiddleware
• RequestLoggingMiddleware
• ExceptionMiddleware

Middleware Registration

app.UseNemeiaMiddleware();

CorrelationId

Automatically generates:

X-Correlation-Id

for every request.

Request Logging

Automatically logs:

• HTTP Method
• Route
• Status Code
• Execution Time
• CorrelationId

Example:

HTTP GET /api/users/1
responded 200
in 42 ms
CorrelationId: a1b2c3

Global Exception Handling

Automatically handles:

• ValidationException
• BusinessException
• UnauthorizedException
• ForbiddenException
• NotFoundException
• Internal server errors

MainController

Provides standardized API responses.

Example Controller

[Route("api/users")]
public class UsersController : MainController
{
    [HttpGet("{id}")]
    public async Task<IActionResult> GetById(
        string id,
        CancellationToken cancellationToken)
    {
        var result = await _service
            .GetByIdAsync(id, cancellationToken);

        return CustomResponse(result);
    }
}

Standard Responses

Success

{
  "success": true,
  "message": "Success",
  "statusCode": 200
}

Validation Error

{
  "success": false,
  "statusCode": 422,
  "errors": [
    "Email is invalid"
  ]
}

Internal Server Error

{
  "success": false,
  "statusCode": 500,
  "errors": [
    "Internal server error."
  ]
}

HealthChecks

Registration

builder.Services.AddNemeiaHealthChecks();

Usage

app.UseNemeiaHealthChecks();

Default Endpoint

/health

Custom HealthChecks

The package includes support for custom checks.

Examples:

• ApiHealthCheck
• MemoryHealthCheck
• DiskStorageHealthCheck

Memory HealthCheck

builder.Services
    .AddHealthChecks()
    .AddCheck(
        "memory",
        new MemoryHealthCheck(
            500_000_000));

Disk HealthCheck

builder.Services
    .AddHealthChecks()
    .AddCheck(
        "disk",
        new DiskStorageHealthCheck(
            1_000_000_000));

OpenAPI Responses

Automatically documents:

• 200
• 400
• 401
• 403
• 404
• 422
• 500

HttpContext Extensions

Provides helpers for:

• TraceId
• CorrelationId
• UserAgent
• IP Address

Example:

var traceId = HttpContext.GetTraceId();

Architecture Goals

This package was designed to provide:

• Standardization
• Reusability
• Observability
• Stability
• Scalability
• Enterprise-grade consistency

for modern ASP.NET Core APIs.

Recommended Stack

• .NET 10
• Clean Architecture
• DDD
• CQRS
• MediatR
• MongoDB
• SQL Server
• Scalar
• OpenAPI

Future Improvements

• OpenTelemetry integration
• Distributed tracing
• Pagination headers
• ValidationProblemDetails
• ProblemDetails RFC support
• API Versioning
• Endpoint conventions
• Response examples
• OpenAPI schema generation

License

MIT