User Guide

An integration typically keeps a configured HttpRestClient behind an API wrapper. The wrapper exposes application operations, while the client prepares HTTP messages, processes responses, and applies the recovery rules you select.

Configuration and Lifetime

The underlying HttpClient owns the HTTP transport. HttpRestClient adds the base address, default request headers, content formatters, retry policy, and error handlers used by the integration. Configure these before making requests.

When the application supplies an HttpClient, decide who owns its lifetime: by default, disposing the wrapper disposes the supplied client. Pass disposeClient: false when the application manages that lifetime. The client configuration guide covers both supplied and shared clients.

A request scope supplies temporary headers or properties for its lifetime. Use it for operation-specific context, and dispose it to restore the previous settings. The request customization guide explains explicit scopes, the fluent scope API, and request/response events.

The Request Lifecycle

A request passes through these stages:

  1. The client creates the HTTP message using its default and scoped configuration.
  2. BeforeSendingRequest gives subscribers an opportunity to modify the outgoing message.
  3. The underlying HttpClient sends it. A configured connection retry policy can schedule another attempt after a transient connection failure or a timeout.
  4. AfterReceivingResponse exposes a received response before further processing.
  5. A successful response is read in the form requested by the caller. An error response is offered to registered error handlers; if none recovers by retrying, the call fails with HttpResponseException.

The request helpers let you choose typed objects, raw bodies, or lower-level HTTP control. Typed responses need a registered formatter that can read the response's media type into the requested model; content formatters also write object payloads in a selected format.

Failure and Recovery

Connection failures, HTTP error responses, and content failures need different treatment. A retry policy controls transient connection failures. Error handlers decide whether an HTTP error response can be retried, while formatter or model problems must be corrected to read the response successfully.

Set retry limits deliberately. The connection retry policy and each retrying error handler count only their own retries, so their limits do not add up to one limit for a call: a call that fails in several ways can be retried more times than any one limit allows. The error handling guide explains how to retry connection failures, how handlers retry error responses, and how to read structured errors.