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

# SAIF.Web.API.Clients overview

> **Documentation context:** Packaged Component (NuGet)

`SAIF.Web.API.Clients` is the client-side integration layer for the SAIF JSON Web API contract. It wraps RestSharp so a consuming application can invoke a SAIF Web API with uniform authentication, caller-identity headers, retry-on-transient-failure, JSON serialization/deserialization, and translation of HTTP failures into typed SAIF exceptions.

## Purpose
- Provide a single client type, `JsonHttpClient`, that a consuming application constructs once per target service and uses to issue GET/POST/PUT/PATCH/DELETE requests against a SAIF JSON Web API, without hand-writing HTTP, authentication, retry, or JSON-shape-normalization code.
- Translate HTTP-level failures into the shared `SAIF.API.Exceptions.*` exception hierarchy defined in [SAIF.Web.API.Core](../saif-web-api-core/overview.md), so consumers can catch domain exceptions instead of transport or RestSharp types.
- Consumed by any .NET Framework application that needs to call a SAIF Web API service; it does not itself expose an HTTP endpoint.
- This library also shares its source files with the `SAIF.Web.API.Clients.35` sibling project, which compiles the same `.cs` files against `net35` for callers that cannot target `.NET Framework 4.6.2`*.

## Responsibilities
- Authenticate outbound requests (Windows NTLM by default, or a caller-supplied `RestSharp.Authenticators.IAuthenticator`).
- Attach caller-identity headers and, optionally, forward the ambient ASP.NET user's identity.
- Retry transient transport/gateway failures with a fixed delay before surfacing them as errors.
- Serialize request bodies and normalize response payload shapes into a uniform result type.
- Translate non-2xx/3xx HTTP responses into typed `SAIF.API.Exceptions.*` exceptions.

## Key components
- `JsonHttpClient`: the sole public entry point; owns the single HTTP execution funnel that every verb method routes through.
- `JsonSerializer`: `RestSharp.Serializers.ISerializer` adapter over `Newtonsoft.Json.JsonSerializer`.
- `ExceptionHandler`: stateless static component mapping HTTP status/content to `SAIF.API.Exceptions.*` types.
- `ClientInfo`: unvalidated DTO carrying caller-identity values (`MachineName`, `ApplicationId`, `UserId`).
- `HttpContextExtensions`: extension method normalizing an ambient Windows identity to a bare account name.
- `EnvironmentSetting`: dormant public key/value DTO with no consumer anywhere in this repository*.

## 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. Statements
> marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- `src/SAIF.Web.API.Clients/JsonHttpClient.cs`
- `src/SAIF.Web.API.Clients/ExceptionHandler.cs`
- `src/SAIF.Web.API.Clients/JsonSerializer.cs`
- `src/SAIF.Web.API.Clients/ClientInfo.cs`
- `src/SAIF.Web.API.Clients/EnvironmentSetting.cs`
- `src/SAIF.Web.API.Clients/Extensions/HttpContextExtensions.cs`
- `src/SAIF.Web.API.Clients/SAIF.Web.API.Clients.csproj`
- `src/SAIF.Web.API.Clients.35/SAIF.Web.API.Clients.35.csproj`