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

# 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](../saif-web-api-clients/overview.md), 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](business-rules.md#br-core-002-httpstatuscode-carried-by-every-saifexception-subtype), [BR-CORE-003](business-rules.md#br-core-003-fixed-default-exception-messages)).
- Carry an `HttpStatusCode` on every `SAIFException`-derived instance so HTTP-facing consumers can associate/read a status after construction ([BR-CORE-002](business-rules.md#br-core-002-httpstatuscode-carried-by-every-saifexception-subtype)).
- 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](business-rules.md#br-core-004-errorresponse-default-error-message)).
- `SAIFException`: abstract base exception carrying an `HttpStatusCode` ([BR-CORE-002](business-rules.md#br-core-002-httpstatuscode-carried-by-every-saifexception-subtype)).
- `NoMatchingDataException`, `UnauthorizedAccessException`, `InternalServerError`, `InvalidDataException`: concrete `SAIFException` subtypes, each with a fixed default message ([BR-CORE-003](business-rules.md#br-core-003-fixed-default-exception-messages)); `InvalidDataException` additionally carries per-field validation failures ([BR-CORE-001](business-rules.md#br-core-001-invaliddataexception-validation-failure-projection)).
- `BuildInfo`: static-usage utility class exposing `GetBuildInfo`, a build/version-metadata file reader.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.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.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`