---
title: SAIF.NetCore.HttpClients overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Framework
last_reviewed: 2026-10-02
library: SAIF.NetCore.HttpClients
reference_type: package
---

# SAIF.NetCore.HttpClients overview

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

SAIF.NetCore.HttpClients is a packaged implementation library that provides a single reusable outbound JSON HTTP client (`HttpJsonClient`) for other SAIF.NetCore libraries and consuming applications, wrapping RestSharp 106 and implementing the `IHttpJsonClient`/`IHttpRequestResult` contracts declared in SAIF.NetCore.ServiceContracts.

## Purpose
- Provide a single, reusable implementation of `IHttpJsonClient`/`IHttpRequestResult` so that SAIF.NetCore libraries and applications can issue outbound JSON HTTP requests (DELETE/GET/PATCH/POST/PUT, sync and async) without depending on RestSharp or Newtonsoft.Json types directly.
- Supply bearer, HTTP Basic, and NTLM (explicit or current-identity) authentication for outgoing calls, caller-identity header propagation (`Client-Name`, `Application-ID`, `Client-User`), configurable retry-on-status-code behavior, and result/error normalization.
- Consumed by other SAIF.NetCore implementation libraries (for example SAIF.NetCore.ServiceExtensions, SAIF.NetCore.WindowsService, SAIF.NetCore.DBConnectionClient, SAIF.NetCore.OIDC, SAIF.NetCore.NtlmApiAuth) that resolve `IHttpJsonClient` through dependency injection.

## Responsibilities
- Implement the outbound HTTP request/response lifecycle: client creation, request construction, execution, retry, and result normalization.
- Hold per-instance request state (base URL, `ClientInfo`, timeout override, `HttpClientOptions`, bearer token, custom headers, NTLM authenticator, last result) that callers configure before issuing requests.
- Offer result-conversion helpers so callers can deserialize JSON content and read response headers in a strongly typed way.

## Key components
- `HttpJsonClient`: the request facade — construction, authentication setup, verb methods, and the private request/execute/retry pipeline.
- `HttpRequestResult`: the result model populated after each call, with `GetResult<T>`/`GetContent<T>` conversion helpers.
- `HttpJsonClientExtensions`: static content/header conversion helpers (`ToReturnType<T>`, `GetHeaderValue<T>`).
- `ClientInfo`: the caller-identity value object (machine name, application ID, user name) propagated as request headers.
- `ClientNotInitializedException`: thrown when a verb method is called before both `ClientInfo` and the base URL are set.

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

## Sources
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs`
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpRequestResult.cs`
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClientExtensions.cs`
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/ClientInfo.cs`
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/Exceptions/ClientNotInitializedException.cs`
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients.csproj`