--- title: SAIF.Web.API.Clients operations and processes summary: Business and technical operations supported by this library. status: draft owner: bendy last_reviewed: 2026-09-15 library: SAIF.Web.API.Clients reference_type: package --- # SAIF.Web.API.Clients operations and processes This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under `operations/`. `SAIF.Web.API.Clients` performs no data access, so no operation below carries a Tables or SQL citation. ## Operation catalog | Operation | Intent | Trigger | Inputs | Outputs | Rules | | --- | --- | --- | --- | --- | --- | | [GetResult\](operations/get-result.md) | Retrieve a single typed value from a GET call. | Direct call by a consuming application. | `methodUriSegment`, generic type argument `T`. | A single `T`, or `default(T)`. | [BR-CLI-001](business-rules.md#br-cli-001-ntlm-default-authentication), [BR-CLI-012](business-rules.md#br-cli-012-response-payload-shape-normalization), [BR-CLI-013](business-rules.md#br-cli-013-single-value-result-coercion) | | [GetResults\](operations/get-results.md) | Retrieve a typed collection from a GET call. | Direct call by a consuming application. | `methodUriSegment`. | `T[]`. | [BR-CLI-012](business-rules.md#br-cli-012-response-payload-shape-normalization) | | [GetResponse\](operations/get-response.md) | Retrieve the full response envelope from a GET call. | Direct call, or delegated from `GetResults`. | `methodUriSegment`. | `ApiResponse`. | [BR-CLI-009](business-rules.md#br-cli-009-response-success-flag), [BR-CLI-012](business-rules.md#br-cli-012-response-payload-shape-normalization), [BR-CLI-014](business-rules.md#br-cli-014-responding-server-capture) | | [PostJson / PutJson / PatchJson / DeleteJson](operations/write-operations.md) | Send a JSON request body via POST, PUT, PATCH, or DELETE and retrieve the response envelope. | Direct call by a consuming application. | `methodUriSegment`, `requestBody`. | `ApiResponse`. | [BR-CLI-002](business-rules.md#br-cli-002-caller-identity-headers-required), [BR-CLI-009](business-rules.md#br-cli-009-response-success-flag), [BR-CLI-012](business-rules.md#br-cli-012-response-payload-shape-normalization), [BR-CLI-014](business-rules.md#br-cli-014-responding-server-capture) | | [GetJsonResponse](operations/get-json-response.md) | Execute the single shared HTTP request funnel used by every public verb method. | Every public verb method; also re-entrant on retry. | URI segment, HTTP method, optional body, remaining retry budget. | Internal `JsonResponse`. | [BR-CLI-001](business-rules.md#br-cli-001-ntlm-default-authentication), [BR-CLI-002](business-rules.md#br-cli-002-caller-identity-headers-required), [BR-CLI-003](business-rules.md#br-cli-003-on-behalf-of-user-forwarding), [BR-CLI-005](business-rules.md#br-cli-005-transient-failure-retry), [BR-CLI-006](business-rules.md#br-cli-006-non-success-response-failure-conversion), [BR-CLI-009](business-rules.md#br-cli-009-response-success-flag), [BR-CLI-010](business-rules.md#br-cli-010-per-client-request-timeout), [BR-CLI-011](business-rules.md#br-cli-011-date-time-zone-handling-consistency), [BR-CLI-015](business-rules.md#br-cli-015-json-only-content-handling) | | [GetApiResponse\](operations/get-api-response.md) | Project a transport-level `JsonResponse` into the public `ApiResponse` envelope. | `GetResponse` and the write operations. | `JsonResponse`. | `ApiResponse`. | [BR-CLI-012](business-rules.md#br-cli-012-response-payload-shape-normalization), [BR-CLI-014](business-rules.md#br-cli-014-responding-server-capture) | | [GetContentArray\](operations/get-content-array.md) | Normalize a JSON payload (array, object, or scalar) into a uniform `T[]`. | `GetResult` step 6; `GetApiResponse` step 1. | `jsonContent`, `DateTimeZoneHandling`. | `T[]` (may be empty; may be `null`). | [BR-CLI-011](business-rules.md#br-cli-011-date-time-zone-handling-consistency), [BR-CLI-012](business-rules.md#br-cli-012-response-payload-shape-normalization), [BR-CLI-013](business-rules.md#br-cli-013-single-value-result-coercion), [BR-CLI-016](business-rules.md#br-cli-016-deserialization-failure-masking) | | [EnsureSuccessfulResponse](operations/ensure-successful-response.md) | Guard a response's success status and route failures to exception mapping. | `GetJsonResponse` step 11. | `IRestResponse`. | None (void), or a thrown `SAIFException`. | [BR-CLI-006](business-rules.md#br-cli-006-non-success-response-failure-conversion) | | [ToKnownError](operations/to-known-error.md) | Map an HTTP failure status and response content to a typed SAIF exception. | `EnsureSuccessfulResponse` step 4; also directly callable by consumers. | `HttpStatusCode`, raw response content. | Always throws. | [BR-CLI-007](business-rules.md#br-cli-007-http-status-to-exception-type-mapping), [BR-CLI-008](business-rules.md#br-cli-008-exception-message-source-preference), [BR-CLI-017](business-rules.md#br-cli-017-failure-message-source-selection) | | [Serialize (JsonSerializer)](operations/serialize-request-body.md) | Serialize a request body to indented JSON for the outbound request. | RestSharp invokes it when `AddJsonBody` content is written. | `obj` (the request body). | The serialized JSON string. | [BR-CLI-011](business-rules.md#br-cli-011-date-time-zone-handling-consistency) | | [DomainlessUser](operations/domainless-user.md) | Normalize an ambient Windows identity to a bare account name. | `GetJsonResponse` step 8; also directly callable by consumers. | Ambient `HttpContext`. | User name without domain qualifier. | [BR-CLI-004](business-rules.md#br-cli-004-forwarded-user-name-normalization) | ## Process flow diagram The following diagram visualizes the primary request/response flow shared by every public verb method. ```mermaid flowchart TD Start([Verb method called]) --> Funnel["GetJsonResponse: build
client, add headers,
serialize body"] Funnel --> Execute[RestSharp client.Execute] Execute --> Retry{"Status in
RetryOnStatusCodes
and retries remain?"} Retry -->|Yes| Sleep["Thread.Sleep, retry"] --> Funnel Retry -->|No| Guard{EnsureSuccessfulResponse
and status is failure?} Guard -->|Yes| Throw([Throw SAIFException]) Guard -->|No| Normalize["GetApiResponse /
GetContentArray"] Normalize --> EndOk(["Return T /
ApiResponse<T>"]) ``` ## Failure and edge-case behavior - A retryable status (default `0`, `401`, `502`, `503`) is retried up to 3 times with a 1000 ms delay; only the final attempt's outcome reaches the caller ([BR-CLI-005](business-rules.md#br-cli-005-transient-failure-retry)). - When `EnsureSuccessfulResponse` is `true` (the default), a non-2xx/3xx status throws a typed `SAIF.API.Exceptions.*` exception and the calling verb method does not return normally ([BR-CLI-006](business-rules.md#br-cli-006-non-success-response-failure-conversion), [BR-CLI-007](business-rules.md#br-cli-007-http-status-to-exception-type-mapping)). - A deserialization failure inside `GetContentArray` does not propagate: for a `string` target type the exception message is substituted as the value, and for any other target type an empty result is returned ([BR-CLI-016](business-rules.md#br-cli-016-deserialization-failure-masking)). - `GetResult` catches only `InvalidCastException` around the single-element array access; an empty result array raises an uncaught `IndexOutOfRangeException`*. - Enabling `SetOnBehalfOfUserHeaders` without an ambient ASP.NET `HttpContext` (for example in a console/service/test host) throws `NullReferenceException`, because no guard exists ([BR-CLI-003](business-rules.md#br-cli-003-on-behalf-of-user-forwarding)). > **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. ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Architecture](architecture.md) - [Dependencies](dependencies.md) - [Business rules](business-rules.md) - [API reference](api/index.md) ## 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/Extensions/HttpContextExtensions.cs`