---
title: JsonHttpClient
summary: API reference for JsonHttpClient.
status: draft
owner: bendy
last_reviewed: 2026-09-15
library: SAIF.Web.API.Clients.35
reference_type: package
---

# JsonHttpClient

`JsonHttpClient` is the public façade of this library: given a base URI, caller identity (`ClientInfo`), and an authenticator, it issues a JSON HTTP request to a SAIF Web API via RestSharp and returns a typed result, a typed result array, or a full `ApiResponse<T>` envelope — or throws a typed `SAIFException` subtype sourced from `SAIF.Web.API.Core`. It owns request construction, identity/impersonation header injection, retry, and error-gate orchestration; `JsonSerializer` and `ExceptionHandler` are collaborators it drives internally.

## Purpose
- Serve as the single entry point consumers use to call a SAIF Web API without handling HTTP transport, retry, serialization, or error-translation concerns directly.
- Enforce identity propagation ([BR-01](../../business-rules.md#br-01-identity-headers-on-every-request)), default NTLM authentication ([BR-02](../../business-rules.md#br-02-default-ntlm-authentication)), transient-failure retry ([BR-05](../../business-rules.md#br-05-transient-failure-retry)), and typed error translation ([BR-06](../../business-rules.md#br-06-unsuccessful-response-raises-typed-exception)) on every request.
- Apply type-specific unwrapping rules (string unquoting, primitive conversion, byte-array decoding, null/cast fallbacks) when a caller asks for a single scalar/object value via `GetResult<T>` ([BR-11](../../business-rules.md#br-11-string-result-unquoting)–[BR-15](../../business-rules.md#br-15-cast-failure-default-result)).

## Context
- Namespace: `SAIF.Web.API.Clients`
- Assembly/package: `SAIF.Web.API.Clients` (net35 build variant; not shipped by the current package definition — see [Overview](../../overview.md))

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `TimeoutOverride` | `public int TimeoutOverride { get; }` (default `0`) | Request timeout in milliseconds applied when greater than zero ([BR-03](../../business-rules.md#br-03-conditional-timeout-override)); `0` defers to the RestSharp/`HttpWebRequest` default. Get-only; set through the constructor. |
| `DateTimeZoneHandling` | `public DateTimeZoneHandling DateTimeZoneHandling { get; set; }` (default `Local`) | Newtonsoft time-zone handling applied to both serialization and deserialization of request/response payloads. |
| `EnsureSuccessfulResponse` | `public bool EnsureSuccessfulResponse { get; set; }` (default `true`) | When true, non-2xx/3xx responses are converted into typed exceptions via `ExceptionHandler` ([BR-06](../../business-rules.md#br-06-unsuccessful-response-raises-typed-exception)). |
| `SetOnBehalfOfUserHeaders` | `public bool SetOnBehalfOfUserHeaders { get; set; }` (default `false`) | When true, adds an `OnBehalfOfUser` header sourced from the current `HttpContext` ([BR-04](../../business-rules.md#br-04-on-behalf-of-header-forwarding)); has no working implementation in this .35 variant since the supporting extension method is excluded from compilation.* |
| `RetryDelayInMs` | `public int RetryDelayInMs { get; set; }` (default `1000`) | Delay, in milliseconds, between retry attempts for transient failures ([BR-05](../../business-rules.md#br-05-transient-failure-retry)). |
| `RetryOnStatusCodes` | `public IEnumerable<HttpStatusCode> RetryOnStatusCodes { get; set; }` (default `(HttpStatusCode)0`, `BadGateway`, `ServiceUnavailable`, `Unauthorized`) | Set of statuses considered retryable, including 401 — meaning an authentication failure is retried before an exception is raised. |
| ctor | `public JsonHttpClient(Uri serviceBaseUri, ClientInfo clientInfo, IAuthenticator authenticator)` | Canonical constructor; a null `authenticator` falls back to `NtlmAuthenticator` ([BR-02](../../business-rules.md#br-02-default-ntlm-authentication)). |
| ctor | `public JsonHttpClient(Uri serviceBaseUri, ClientInfo clientInfo)` | Delegates to the canonical constructor with `new NtlmAuthenticator()`. |
| ctor | `public JsonHttpClient(Uri serviceBaseUri, ClientInfo clientInfo, IAuthenticator authenticator, int timeoutOverride)` | Canonical constructor plus a request timeout override. |
| ctor | `public JsonHttpClient(Uri serviceBaseUri, ClientInfo clientInfo, int timeoutOverride)` | Adds a timeout override but forces `NtlmAuthenticator`; the supplied-authenticator overload is not reachable from this constructor chain.* |
| `GetResult<T>` | `public T GetResult<T>(string methodUriSegment)` | Issues a GET and returns a single deserialized value of type `T`, applying type-specific unwrapping rules ([BR-11](../../business-rules.md#br-11-string-result-unquoting)–[BR-15](../../business-rules.md#br-15-cast-failure-default-result)). |
| `GetResults<T>` | `public T[] GetResults<T>(string methodUriSegment)` | Issues a GET and returns the `Results` array from the full `ApiResponse<T>` envelope. |
| `GetResponse<T>` | `public ApiResponse<T> GetResponse<T>(string methodUriSegment)` | Issues a GET and returns the full `ApiResponse<T>` envelope. |
| `PostJson<T>` | `public ApiResponse<T> PostJson<T>(string methodUriSegment, object body)` | Issues a POST with a JSON-serialized body and returns the full envelope. |
| `PutJson<T>` | `public ApiResponse<T> PutJson<T>(string methodUriSegment, object body)` | Issues a PUT with a JSON-serialized body and returns the full envelope. |
| `PatchJson<T>` | `public ApiResponse<T> PatchJson<T>(string methodUriSegment, object body)` | Issues a PATCH with a JSON-serialized body and returns the full envelope. |
| `DeleteJson<T>` | `public ApiResponse<T> DeleteJson<T>(string methodUriSegment, object body)` | Issues a DELETE with a JSON-serialized body and returns the full envelope. |

## Non-public implementation details
| Member | Signature | Purpose |
| --- | --- | --- |
| `GetResultsFromApiResponse<T>` | `private T[] GetResultsFromApiResponse<T>(...)` | Non-public helper that extracts the results array from a deserialized envelope. |
| `GetApiResponse<T>` | `private ApiResponse<T> GetApiResponse<T>(...)` | Non-public helper that builds the `ApiResponse<T>` envelope from a wrapped `JsonResponse`, including server-name and status metadata ([BR-10](../../business-rules.md#br-10-server-name-from-response-header)). |
| `GetJsonResponse` | `private JsonResponse GetJsonResponse(...)` | Non-public core method implementing request construction, header injection, retry, and error-gate orchestration (see [Execute JSON API request and return typed envelope](../../operations/op-01-execute-json-api-request.md)). |
| `GetContentArray<T>` | `internal static List<T> GetContentArray<T>(string content, DateTimeZoneHandling handling)` | Internal helper that deserializes JSON content into a normalized list, returning the exception message as a single string result on failure for `T = string` ([BR-08](../../business-rules.md#br-08-array-deserialization-normalization), [BR-09](../../business-rules.md#br-09-string-deserialization-failure-fallback)). |

## Behavioral notes
- The primary workflow implemented by this type is documented step-by-step in [Execute JSON API request and return typed envelope](../../operations/op-01-execute-json-api-request.md) and [Get single typed result](../../operations/op-02-get-single-typed-result.md).
- `ApiResponse<T>.Version` is never populated: `GetApiResponse<T>` copies `jsonResponse.Version`, but `GetJsonResponse` never assigns `JsonResponse.Version` when constructing the object, so the value is always null.*
- Only `InvalidCastException` is caught in the `GetResult<T>` object branch; an empty result array instead surfaces as `IndexOutOfRangeException` to the caller.*

## Constraints and usage notes
- In this `.35` build variant, `SetOnBehalfOfUserHeaders` has no working implementation because `Extensions/HttpContextExtensions.cs` is excluded from compilation and `System.Web` is not referenced.*
- This library is a dormant/retired legacy variant — see [Overview](../../overview.md) for the build/packaging status before relying on this type in new consumers.

> **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.Clients/JsonHttpClient.cs