Documentation on Dotnet WebApi Util

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

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

Request pipeline

The library is a thin layer around the standard ASP.NET Core pipeline. WebApiStartup builds the WebApplicationBuilder/WebApplication through one standard sequence, whose pipeline half adds the three built-in middlewares with UseStandardMiddlewares() — AuthenticationMiddleware only when AddTokenAuthentication was registered, with Swagger and CORS (when enabled) served just before it — then any extra middlewares from WebApiStartupOptions.Middlewares, then the controllers:

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

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 invalid-model-state envelope, Swagger, the standard middlewares and controller mapping — and leaves you a single method to implement, ConfigureServices, for your own services. The sequence is tuned through WebApiStartupOptions, and every step in it is also a public extension method, so the same setup can be composed on a plain WebApplicationBuilder without the base class.

Endpoint Toggling

Mon, 01 Jan 0001 00:00:00 +0000

[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 the action runs and a response is returned in one of several shapes. The toggle can be fixed in code or resolved from configuration on every request, so an endpoint can be disabled without a redeploy.

The two forms

The attribute has two constructors — pick one per endpoint:

Security

Mon, 01 Jan 0001 00:00:00 +0000

ArturRios.Util.WebApi ships token authentication and role-based authorization as a small, composable set of pieces: AuthenticationMiddleware extracts and validates the token and attaches the user, a pair of attributes/filters declare access rules, and Credentials/Authentication give you the record types for a login flow.

Two token schemes are supported side by side — the app’s own HMAC JWT and Google ID tokens — and either can be accepted on a given request. Which scheme(s) are enabled, where the token is read from, and how the user is resolved are all controlled by one AuthenticationOptions instance, registered via AddTokenAuthentication.

Middleware & Diagnostics

Mon, 01 Jan 0001 00:00:00 +0000

ArturRios.Util.WebApi ships two request-pipeline middlewares — TraceActivityMiddleware and ExceptionMiddleware — plus TracePropagationHandler, a DelegatingHandler that carries the same trace id onto outgoing HttpClient calls. (The third pipeline middleware, AuthenticationMiddleware, is covered on the Security page.) WebApiStartup adds all of them for you through UseStandardMiddlewares(), as referenced in Architecture and Configuration.

`WebApiMiddleware` and registration order

UseStandardMiddlewares() (ArturRios.Util.WebApi.Configuration) adds the built-in middlewares in a fixed order:

app.UseStandardMiddlewares();
// 0. UseForwardedHeaders — no-op until ForwardedHeadersOptions is configured
// 1. TraceActivityMiddleware — assigns/propagates a W3C trace id
// 2. ExceptionMiddleware — turns unhandled exceptions into a JSON error envelope
// 3. Swagger JSON + UI — only when the Swagger generator was registered
// 4. UseCors(policy) — only when a CORS policy name is passed
// 5. AuthenticationMiddleware — only when AddTokenAuthentication was registered

TraceActivityMiddleware runs first so the trace id is available to everything downstream, including exception logging; ExceptionMiddleware runs next so it can catch exceptions thrown by authentication or the endpoint itself; Swagger and CORS come before AuthenticationMiddleware (see Security), which runs last, so the Swagger UI and CORS preflight requests never need a token. WebApiStartup calls it as the first step of the pipeline; on a plain WebApplication, call it yourself.

HTTP Client

Mon, 01 Jan 0001 00:00:00 +0000

ArturRios.Util.WebApi gives you a thin base for typed clients that call another web API: BaseWebApiClient owns a shared HttpGateway, and BaseWebApiClientRoute groups related endpoints under a base URL with helpers for authenticating and carrying the resulting bearer token.

`BaseWebApiClient`

BaseWebApiClient is abstract and exposes a protected HttpGateway Gateway that every route object uses to issue requests. It has two constructors:

BaseWebApiClient(HttpClient httpClient) — wraps an existing HttpClient. Prefer this one: it lets the client be created through IHttpClientFactory (via AddHttpClient<T>()), which manages the underlying HttpClient’s lifetime and connection pooling for you and is what lets you attach message handlers like TracePropagationHandler.
BaseWebApiClient(string baseUrl) — constructs its own HttpClient with BaseAddress = baseUrl. Simpler for quick/manual use, but you lose IHttpClientFactory’s pooling and the ability to attach handlers through DI.

Both constructors call the abstract SetRoutes() method before returning, so a derived class implements it to instantiate its route objects against the shared Gateway:

Responses

Mon, 01 Jan 0001 00:00:00 +0000

ToActionResult is an extension method (in OutputActionResultExtensions, namespace ArturRios.Util.WebApi.AspNetCore) that converts ArturRios.Output envelopes — DataOutput<T>, ProcessOutput, and PaginatedOutput<T> — into ASP.NET Core ActionResults, so a controller action never has to hand-pick a status code for the happy and unhappy paths itself.

ToActionResult replaces the static ResponseResolver.Resolve(output, ...), which was removed in 5.0.0 with no change in behavior: replace each ResponseResolver.Resolve(output, ...) call with output.ToActionResult(...).

`ToActionResult` overloads

ToActionResult has three overloads, one per envelope type:

Documentation on Dotnet WebApi Util

Architecture

Request pipeline

Configuration

Endpoint Toggling

The two forms

Security

Middleware & Diagnostics

WebApiMiddleware and registration order

HTTP Client

BaseWebApiClient

Responses

ToActionResult overloads

`WebApiMiddleware` and registration order

`BaseWebApiClient`

`ToActionResult` overloads