Skip to content

SAIF.Web.API.Core overview

Documentation context: Packaged Component (NuGet)

SAIF.Web.API.Core is a shared contracts/cross-cutting library that supplies common wire-format data-transfer objects and a typed exception hierarchy so that HTTP status/error semantics can be represented as strongly-typed .NET exceptions rather than raw status codes. It defines no business logic, no services, no controllers, and performs no network or database I/O.

Purpose

  • Define response envelope data-transfer objects (ApiResponse<T>, ErrorResponse) used to represent API results and serializable error payloads.
  • Define a typed exception hierarchy rooted at the abstract SAIFException (NoMatchingDataException, UnauthorizedAccessException, InternalServerError, InvalidDataException) so that HTTP failure semantics can be expressed as strongly-typed .NET exceptions.
  • Provide BuildInfo.GetBuildInfo, a standalone static utility that reads an optional version*.dat-pattern build/version metadata file from a caller-supplied directory.
  • Consumed within this repository only by SAIF.Web.API.Clients, which uses ApiResponse<T> in its JsonHttpClient and the SAIF.API.Exceptions.* types in its ExceptionHandler.ToKnownError. It has no independent NuGet package identity of its own — it is compiled as a separate assembly but bundled into the SAIF.Web.API.Clients NuGet package via IncludeReferencedProjects=true.

Responsibilities

  • Define response envelope DTOs (ApiResponse<T>, ErrorResponse) that represent API results and serializable error payloads.
  • Define a typed exception hierarchy so HTTP failure semantics can be expressed as strongly-typed .NET exceptions rather than raw status codes (BR-CORE-002, BR-CORE-003).
  • Carry an HttpStatusCode on every SAIFException-derived instance so HTTP-facing consumers can associate/read a status after construction (BR-CORE-002).
  • Provide BuildInfo.GetBuildInfo, a build/version-metadata file reader unrelated in purpose to the response/exception types; its co-location in this project is organizational/historical rather than architecturally cohesive*.

Key components

  • ApiResponse<T>: generic response envelope carrying server/version metadata, an HttpStatusCode, and a typed results array.
  • ErrorResponse: [DataContract] serializable error payload with a code, message, ID, and URL (BR-CORE-004).
  • SAIFException: abstract base exception carrying an HttpStatusCode (BR-CORE-002).
  • NoMatchingDataException, UnauthorizedAccessException, InternalServerError, InvalidDataException: concrete SAIFException subtypes, each with a fixed default message (BR-CORE-003); InvalidDataException additionally carries per-field validation failures (BR-CORE-001).
  • BuildInfo: static-usage utility class exposing GetBuildInfo, a build/version-metadata file reader.

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.Core/SAIF.Web.API.Core.csproj
  • src/SAIF.Web.API.Core/ApiResponse.cs
  • src/SAIF.Web.API.Core/BuildInfo.cs
  • src/SAIF.Web.API.Core/ErrorResponse.cs
  • src/SAIF.Web.API.Core/SAIFException.cs
  • src/SAIF.Web.API.Clients/SAIF.Web.API.Clients.csproj