Skip to content

SAIF.Web.API overview

Documentation context: Packaged Component (NuGet)

SAIF.Web.API is a cross-cutting infrastructure library for ASP.NET Web API 2 (System.Web.Http) host applications. It supplies a response/error post-processing message handler, a delegated role-based authorization attribute, an HTTPS-enforcement action filter, a static exception-to-HTTP-status mapper, and a request-header extension helper. It contains no controllers, no entry point, and no database access; every authorization decision and configuration value is ultimately assumed to be supplied by the hosting application or by the SAIF.Framework.Core package — no such supply or registration is observed inside this library.*

Purpose

  • Provide reusable, pluggable ASP.NET Web API 2 pipeline components — a message handler, an authorization attribute, an action filter, and static helpers — that a hosting Web API application registers to obtain consistent response shaping, correlation-ID issuance, observability, transport security, and role-based authorization; no such registration exists in this repository.*
  • Consumed by ASP.NET Web API 2 host applications (net462) that register ApiResponseHandler in HttpConfiguration.MessageHandlers and decorate their own controllers/actions with [SaifAuthorize] and/or [RequireSSL]; no registration call site exists in this repository, so this describes the intended host-side usage pattern rather than an observed registration.*

Responsibilities

  • Post-process every outbound Web API response to add a correlation MessageID/MessageIDUrl, redact sensitive request content from debug traces, and rewrite non-success responses into a structured ErrorResponse body (ApiResponseHandler).
  • Enforce role/resource-based authorization on Web API controllers/actions by delegating the authorization decision to an injected ISecurityApiClient (SaifAuthorizeAttribute).
  • Enforce HTTPS on Web API actions, with a configurable relaxation for local/developer requests (RequireSSLAttribute).
  • Provide a static, reusable mapping from typed SAIF.API.Exceptions.* exceptions to HttpStatusCode values for consuming controllers/exception filters (ExceptionHandler).
  • Provide a generic, never-throwing request-header reader for consumers (HttpRequestExtensions).

Key components

  • ApiResponseHandler: DelegatingHandler that times each request, resolves ILogService/IEnvironmentService per request, normalizes error responses, adds a Server-Name header unconditionally, and traces/logs each request when ILogService is resolved (no trace/log otherwise).
  • SaifAuthorizeAttribute: sealed AuthorizeAttribute override that resolves ISecurityApiClient/IEnvironmentService per request and authorizes on OR semantics across caller-supplied role names.
  • RequireSSLAttribute: ActionFilterAttribute that redirects non-HTTPS requests to HTTPS, with a local-request exemption controlled by the ambient application's RequireSSLForLocal app setting; no such application or setting exists in this repository.*
  • ExceptionHandler: static utility mapping SAIF.API.Exceptions.* types to HttpStatusCode values via catch-clause type dispatch.
  • HttpRequestExtensions: static extension method (TryGetFirstHeader) for reading a request header value without throwing.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • src/SAIF.Web.API/SAIF.Web.API.csproj
  • src/SAIF.Web.API/ApiResponseHandler.cs
  • src/SAIF.Web.API/ExceptionHandler.cs
  • src/SAIF.Web.API/HttpRequestExtensions.cs
  • src/SAIF.Web.API/RequireSSLAttribute.cs
  • src/SAIF.Web.API/SaifAuthorizeAttribute.cs