Documentation

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

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 IAuthenticatedUser</i>"]
    Auth --> Endpoint["Controller / endpoint"]
    Endpoint --> Resolver["ToActionResult<br/><i>Output envelope → ActionResult</i>"]
    Resolver --> Client

Feature areas

AreaWhat it doesDocs
Configuration / bootstrapWebApiStartup runs one standard sequence — configuration loading, Swagger, the middleware pipeline — leaving you a single ConfigureServices method, and every step is also a standalone extension; 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 IAuthenticatedUser; [Authorize], [AllowAnonymous] and [RoleRequirement(...)] declare access rules.Security
Middleware & diagnosticsExceptionMiddleware converts unhandled exceptions into a JSON error envelope; TraceActivityMiddleware and TracePropagationHandler propagate the W3C traceparent/tracestate across a request and its outgoing calls.Middleware & Diagnostics
HTTP clientBaseWebApiClient / 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
Responsesoutput.ToActionResult(...) 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 ToActionResult 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.

Architecture

This page shows how the pieces of ArturRios.Util.WebApi fit together: the request pipeline, the security model, the response envelope, and the design…

Configuration

WebApiStartup is the abstract base class you derive from to bootstrap an ASP.NET Core host: it runs one standard, opinionated sequence — configuration loading, controllers, the…

Endpoint Toggling

[EndpointToggle] is an action filter attribute that turns a single endpoint on or off. When the endpoint is disabled, the request is short-circuited **before…

Security

ArturRios.Util.WebApi ships token authentication and role-based authorization as a small, composable set of pieces: AuthenticationMiddleware extracts and…

Middleware & Diagnostics

ArturRios.Util.WebApi ships two request-pipeline middlewares — TraceActivityMiddleware and ExceptionMiddleware — plus TracePropagationHandler, a…

HTTP Client

ArturRios.Util.WebApi gives you a thin base for typed clients that call another web API: BaseWebApiClient owns a shared HttpGateway, and…

Responses

ToActionResult is an extension method that converts ArturRios.Output envelopes — DataOutput<T>, ProcessOutput, and PaginatedOutput<T> — into ASP.NET…