USE FOR: Making HTTP API calls using RestSharp's fluent request builder with automatic serialization, authenticators, and response handling. Use when consuming REST APIs that need configurable serialization, file uploads, and built-in authentication support without defining interfaces.
DO NOT USE FOR: Type-safe compile-time API clients (use Refit), GraphQL queries (use StrawberryShake), or new projects where HttpClientFactory with source-generated serialization is preferred (use HttpClient with System.Text.Json).
USE FOR: Making HTTP API calls using RestSharp's fluent request builder with automatic serialization, authenticators, and response handling. Use when consuming REST APIs that need configurable serialization, file uploads, and built-in authentication support without defining interfaces.
DO NOT USE FOR: Type-safe compile-time API clients (use Refit), GraphQL queries (use StrawberryShake), or new projects where HttpClientFactory with source-generated serialization is preferred (use HttpClient with System.Text.Json).
RestSharp is a mature HTTP client library for .NET that simplifies REST API consumption with automatic serialization/deserialization, authenticators, interceptors, and a fluent request builder. Starting with v107, RestSharp wraps internally and can integrate with for proper handler lifecycle management. RestSharp supports JSON (System.Text.Json and Newtonsoft.Json), XML, and custom serializers. It provides built-in authenticators for OAuth1, OAuth2, JWT, and HTTP Basic authentication. RestSharp handles multipart file uploads, query parameters, URL segments, and response deserialization with a consistent API across all HTTP methods.
Create RestClient instances through HttpClientFactory by registering named HttpClient instances and passing them to the RestClient constructor, so that HttpMessageHandler lifetimes are managed by the factory and socket exhaustion is prevented.
Use AddUrlSegment() for path parameters (e.g., "api/products/{id}" with .AddUrlSegment("id", 42)) instead of string interpolation ($"api/products/{id}"), because URL segments are properly encoded and the request template remains readable in logs and interceptors.
Use ExecuteGetAsync<T>() / ExecutePostAsync<T>() instead of GetAsync<T>() / PostAsync<T>() when you need to inspect the full response including status code, headers, and error details, because the Execute* methods return a RestResponse<T> with metadata while the shorthand methods throw on non-success status codes.
Configure serialization explicitly using configureSerialization: s => s.UseSystemTextJson(options) when creating the RestClient to control property naming, null handling, and enum serialization, rather than relying on default serializer settings that may not match the API's expected format.
Use built-in authenticators (JwtAuthenticator, HttpBasicAuthenticator, OAuth2AuthorizationRequestHeaderAuthenticator) rather than manually adding Authorization headers to each request, because authenticators apply consistently to all requests and can be swapped without modifying request-building code.
Pass CancellationToken to all async methods from the calling context (controller, hosted service) so that HTTP requests are cancelled when the client disconnects or the application shuts down, preventing wasted network calls and improving shutdown performance.
Use interceptors for cross-cutting concerns (logging, correlation IDs, metrics) by extending the Interceptor base class and adding instances to RestClientOptions.Interceptors, rather than modifying each request individually, ensuring all requests consistently include the required behavior.
Use AddJsonBody() for JSON payloads and AddFile() for file uploads rather than manually constructing StringContent or MultipartFormDataContent, because RestSharp sets the correct Content-Type headers and handles serialization and encoding automatically.
Handle errors by checking response.IsSuccessful before accessing response.Data and examine response.ErrorException for transport errors and response.Content for API error bodies, rather than only checking the deserialized Data property which is null on failure.
Set MaxTimeout on RestClientOptions to a value appropriate for the downstream service (e.g., 30 seconds for most APIs, 120 seconds for report generation endpoints) rather than using the default infinite timeout, because unresponsive downstream services will hold connections open indefinitely and exhaust the connection pool.
