Kodevy.Platform.API 4.2.2

Kodevy Platform

Shared .NET 8 libraries for building microservices with Clean Architecture. These packages provide the foundational plumbing so your microservices stay consistent, production-ready, and free of boilerplate.

Packages

Installation

dotnet add package Kodevy.Platform.API
dotnet add package Kodevy.Platform.Application
dotnet add package Kodevy.Platform.Domain
dotnet add package Kodevy.Platform.Infra

Install only the layers your project needs. In a Clean Architecture setup:

• API project — Kodevy.Platform.API
• Application project — Kodevy.Platform.Application
• Domain project — Kodevy.Platform.Domain
• Infrastructure project — Kodevy.Platform.Infra

What's Included

Kodevy.Platform.API

• Global exception handling middleware
• Request context middleware
• JWT authentication strategy (configurable)
• Claims-based authorization strategy
• ToHttpResult mapping that returns consistent API envelope metadata (statusCode, path, timestamp, and development stackTrace)
• API versioning via URL segment (/api/v{version}/...)
• Swagger / OpenAPI configuration with per-version documents and JWT bearer support
• Health check extensions (including EF Core database checks)
• Serilog integration

Kodevy.Platform.Application

• ApiClientBase — typed HTTP client with built-in auth token handling
• ApiResult / ServiceResponseWrapper / PaginatedResponseWrapper — standard response wrappers
• ICurrentUserService — access to current authenticated user context (UserId, Email, SessionId, Roles)
• GetRequiredUserId() — helper extension for strict user-id retrieval
• IUnitOfWork — persistence contract
• BaseApplicationSettings / AuthConfiguration / JwtSettings — configuration models

Kodevy.Platform.Domain

• IAuditableEntity — interface for entities with created/modified tracking

Kodevy.Platform.Infra

• DatabaseConnection / DatabaseProvider — multi-provider database setup (SQL Server, PostgreSQL)
• AuditSaveChangesInterceptor — automatic audit field population on save
• RelationalDatabaseExtensions — EF Core registration with environment-based migration behavior
• Serilog database sinks (SQL Server, PostgreSQL)

Configuration

Authentication & Authorization

Configure in appsettings.json:

{
  "AuthConfiguration": {
    "AuthenticationStrategy": "Jwt",
    "AuthorizationStrategy": "Claims"
  },
  "JwtSettings": {
    "Secret": "your-secret-key",
    "Issuer": "your-issuer",
    "Audience": "your-audience",
    "SigningAlgorithm": "HS256",
    "Authority": "",
    "JwksUri": "",
    "RequireHttpsMetadata": true,
    "RefreshOnIssuerKeyNotFound": true,
    "ValidAlgorithms": [],
    "PrivateKeyPem": "",
    "KeyId": "identity-key-1"
  }
}

Compatibility notes:

• Existing HS256 consumers continue to work with SigningAlgorithm: HS256 (default).
• For RS256, set SigningAlgorithm: RS256 and configure either Authority or JwksUri.
• Services validate tokens locally using cached signing keys; no per-request network call is required.

HS256 mode requirements:

• SigningAlgorithm = HS256 (or omitted, default)
• Secret (minimum 32 chars), Issuer, Audience

RS256 mode requirements:

• SigningAlgorithm = RS256
• Issuer, Audience
• one of Authority or JwksUri
• Secret is not required in RS256 mode

Token issuer extras (for auth/identity services):

• PrivateKeyPem - RS256 private key (PEM) used for signing
• KeyId - JWKS key identifier (kid) published with issued tokens

API Versioning (URL Segment)

In your API project startup:

builder.Services.AddControllers();
builder.Services.AddSwaggerConfiguration();

app.UseSwaggerConfiguration();
app.MapControllers();

Controller convention (template standard):

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public sealed class WeatherController : ControllerBase
{
}

Kodevy.Platform.API configures:

• URL segment version reader (/api/v1/...)
• default API version fallback to 1.0 when unspecified
• one Swagger document per API version at /swagger/{groupName}/swagger.json

Database

{
  "DatabaseConfiguration": {
    "Provider": "PostgreSQL",
    "ConnectionString": "Host=localhost;Database=mydb;Username=user;Password=pass"
  }
}

Supported providers: SqlServer, PostgreSQL

Migration behavior:

• Development — migrations are automatically applied on startup
• Production — migrations are not applied automatically. Set RUN_MIGRATIONS_ONLY=true to apply migrations and exit

Used By

These packages are consumed by microservices generated with the Kodevy Microservice Templates:

dotnet new install Kodevy.Templates.Microservice.Init
dotnet new kodevy-microservice-init \
  --organization Contoso \
  --system Platform \
  --microservice Identity

License

MIT