---
title: SAIF.Web.API overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: andmil
last_reviewed: 2026-09-15
library: SAIF.Web.API
reference_type: package
---

# 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.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)

> **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`