Skip to content

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\<T> 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, BR-CLI-012, BR-CLI-013
GetResults\<T> Retrieve a typed collection from a GET call. Direct call by a consuming application. methodUriSegment. T[]. BR-CLI-012
GetResponse\<T> Retrieve the full response envelope from a GET call. Direct call, or delegated from GetResults<T>. methodUriSegment. ApiResponse<T>. BR-CLI-009, BR-CLI-012, BR-CLI-014
PostJson / PutJson / PatchJson / DeleteJson 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<T>. BR-CLI-002, BR-CLI-009, BR-CLI-012, BR-CLI-014
GetJsonResponse 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, BR-CLI-002, BR-CLI-003, BR-CLI-005, BR-CLI-006, BR-CLI-009, BR-CLI-010, BR-CLI-011, BR-CLI-015
GetApiResponse\<T> Project a transport-level JsonResponse into the public ApiResponse<T> envelope. GetResponse<T> and the write operations. JsonResponse. ApiResponse<T>. BR-CLI-012, BR-CLI-014
GetContentArray\<T> Normalize a JSON payload (array, object, or scalar) into a uniform T[]. GetResult<T> step 6; GetApiResponse<T> step 1. jsonContent, DateTimeZoneHandling. T[] (may be empty; may be null). BR-CLI-011, BR-CLI-012, BR-CLI-013, BR-CLI-016
EnsureSuccessfulResponse 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
ToKnownError 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, BR-CLI-008, BR-CLI-017
Serialize (JsonSerializer) 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
DomainlessUser 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

Process flow diagram

The following diagram visualizes the primary request/response flow shared by every public verb method.

flowchart TD
    Start([Verb method called]) --> Funnel["GetJsonResponse: build<br>client, add headers,<br>serialize body"]
    Funnel --> Execute[RestSharp client.Execute]
    Execute --> Retry{"Status in<br>RetryOnStatusCodes<br>and retries remain?"}
    Retry -->|Yes| Sleep["Thread.Sleep, retry"] --> Funnel
    Retry -->|No| Guard{EnsureSuccessfulResponse<br>and status is failure?}
    Guard -->|Yes| Throw([Throw SAIFException])
    Guard -->|No| Normalize["GetApiResponse /<br>GetContentArray"]
    Normalize --> EndOk(["Return T /<br>ApiResponse&lt;T&gt;"])

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).
  • 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, BR-CLI-007).
  • A deserialization failure inside GetContentArray<T> 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).
  • GetResult<T> 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).

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/Extensions/HttpContextExtensions.cs