Documentation

ArturRios.Util.WebApi is a set of building blocks for ASP.NET Core web APIs in .NET. It bundles a base class for bootstrapping the host (configuration, Swagger, middleware pipeline), token authentication that reads the token from the header, a cookie, or either and validates it as the app’s own JWT and/or a Google ID token (with role-based authorization), cross-cutting middleware for exceptions and distributed tracing, a thin typed-HttpClient base for calling other services, and a resolver that turns ArturRios.Output envelopes into ActionResults.

Request pipeline

A typical request set up with the built-in middlewares flows through tracing, exception handling and authentication before it reaches your endpoint:

flowchart LR
    Client["Client request"] --> Trace["TraceActivityMiddleware<br/><i>assigns/propagates W3C traceparent</i>"]
    Trace --> Exception["ExceptionMiddleware<br/><i>catches unhandled exceptions</i>"]
    Exception --> Auth["AuthenticationMiddleware<br/><i>validates the request token, attaches AuthenticatedUser</i>"]
    Auth --> Endpoint["Controller / endpoint"]
    Endpoint --> Resolver["ResponseResolver<br/><i>Output envelope → ActionResult</i>"]
    Resolver --> Client

Feature areas

Area	What it does	Docs
Configuration / bootstrap	`WebApiStartup` wires up configuration loading, Swagger and the middleware pipeline behind a small set of virtual hooks; `WebApiParameters` parses command-line startup args.	Configuration
Security (JWT, Google + roles)	`AuthenticationMiddleware` reads the token from the header, a cookie, or either, and validates it as an app HMAC JWT or a Google ID token (either accepted per request), attaching an `AuthenticatedUser`; `[Authorize]`, `[AllowAnonymous]` and `[RoleRequirement(...)]` declare access rules.	Security
Middleware & diagnostics	`ExceptionMiddleware` converts unhandled exceptions into a JSON error envelope; `TraceActivityMiddleware` and `TracePropagationHandler` propagate a W3C `traceparent` across a request and its outgoing calls.	Middleware & Diagnostics
HTTP client	`BaseWebApiClient` / `BaseWebApiClientRoute` give a typed client a shared `HttpGateway`, route grouping, and helpers to authenticate and carry the resulting bearer token on subsequent calls.	HTTP Client
Responses	`ResponseResolver.Resolve(...)` wraps `DataOutput<T>`, `PaginatedOutput<T>` and `ProcessOutput` in an `ActionResult`, defaulting to 200/400 based on `Success` unless a status code is supplied.	Responses
Endpoint toggling	`[EndpointToggle]` enables or disables a single endpoint from a compile-time flag or a runtime `appsettings.json`/environment-variable value, shaping the disabled response as an empty status code, the action’s default value, a `ProcessOutput` envelope, or a thrown `EndpointDisabledException`.	Endpoint Toggling

Installation

Requires .NET 10 or later.

dotnet add package ArturRios.Util.WebApi

The result envelope

Endpoints return an ArturRios.Output envelope — DataOutput<T> (data + success/errors) or, for operations with no payload, ProcessOutput — and ResponseResolver maps that envelope onto an ActionResult, so success and failure both flow through the same, predictable shape instead of thrown exceptions.

Where to next

Architecture — how the pieces above fit together and the design principles behind them.
Configuration — bootstrapping a host with WebApiStartup and WebApiParameters.
Security — JWT validation modes, cached revalidation, and role-based authorization.
Middleware & Diagnostics — exception handling and distributed tracing.
HTTP Client — building typed clients on top of BaseWebApiClient.
Responses — resolving ArturRios.Output envelopes into ActionResults.
Endpoint Toggling — enabling or disabling individual endpoints from code or configuration.

The source lives at github.com/artur-rios/dotnet-webapi-util, licensed under the MIT License.