Archetypical.Software.Vega.Api.Abstractions 2.9.0

Archetypical.Software.Vega.Api.Abstractions

Base controllers, dependency injection helpers, and common abstractions for building ASP.NET Core APIs, often used with Dapr.

Overview

This package provides a set of tools and conventions to accelerate the development of robust, observable, and configurable web APIs. It includes:

• Simplified application setup (CreateVegaApi, UseVegaApiDefaults).
• Base DbContext (VegaDbContext) with multi-provider support.
• Integrated Dapr features (Distributed Cache, Remote Configuration).
• JWT bearer validation against OIDC discovery, enabled by default.
• Configuration options (VegaApiOptions) to easily enable/disable features like OData, Swagger, OpenTelemetry, Health Checks, etc.
• Standardized configuration loading from appsettings.json and environment variables.

Installation

Install the package via NuGet:

# .NET CLI
dotnet add package Archetypical.Software.Vega.Api.Abstractions

# Package Manager
Install-Package Archetypical.Software.Vega.Api.Abstractions

You will also likely need packages for the features you intend to use, such as:

• Microsoft.EntityFrameworkCore.SqlServer / Npgsql.EntityFrameworkCore.PostgreSQL / etc. (for DbContext)
• Dapr.AspNetCore (for Dapr integration)
• Swashbuckle.AspNetCore (for Swagger, often included by default)
• OpenTelemetry.Extensions.Hosting / OpenTelemetry.Instrumentation.AspNetCore / etc. (for OpenTelemetry)

Basic Usage (Program.cs)

using Archetypical.Software.Vega.Api.Abstractions;

var builder = VegaApiApplication.CreateVegaApi(options =>
{
    options.ServiceName = "MyMicroservice";
    options.ServiceDescription = "Provides core business logic.";

    // Local-only example:
    // options.TurnOff.Authentication = true;

    options.HealthChecks = healthChecksBuilder =>
    {
        // healthChecksBuilder.AddCheck<MyCustomHealthCheck>("custom_check");
        return healthChecksBuilder;
    };
}, args);

// builder.Services.AddScoped<IMyService, MyService>();

var app = builder.Build();

app.UseVegaApiDefaults();

app.Run();

Authentication in Vega, ELI5

By default, Vega services expect callers to send a Bearer JWT. The service downloads public signing keys from the configured OIDC authority, verifies the token signature/lifetime/issuer, and requires a tenant claim named TenantId or tenant_id.

The default dev authority is:

https://idp.dev.archetypical.ai/oidc/

For local tests or throwaway development without tokens, turn authentication off explicitly:

$env:VEGA__API__TurnOff__Authentication="true"

When authentication is enabled, controllers and /db/schema-info plus /db/query require authenticated users. /healthz and /readyz stay anonymous so probes keep working. Injected HttpClient instances forward the inbound bearer token by default.

Documentation

For detailed information on configuration and features, please refer to the documentation in the docs folder:

• Main Documentation Index

Key areas include:

• Configuring VegaApiOptions
• Using CreateVegaApi and UseVegaApiDefaults
• Configuration via appsettings.json and Environment Variables
• Authentication
• Using VegaDbContext
• Dapr Distributed Cache
• Remote Configuration

Building From Source (Contributors)

See docs/building.md for restoring, building, and testing this repository, including the src/Directory.Build.props build-output path convention used to avoid Windows MAX_PATH issues.

Contributing

[Details on contributing, code of conduct, etc.]

License

[License information]