RestSharp: Why .NET's Most Popular HTTP Client Library Finally Rewrote Itself

Hook

With nearly 10,000 stars on GitHub, RestSharp made a radical decision in version 107: throw away 15 years of custom HTTP code and rebuild as a wrapper around Microsoft's HttpClient. For a library this established, that's either visionary or reckless.

Context

Anyone who's written raw HttpClient code in .NET knows the pain. Want to send JSON? Manually serialize your object, wrap it in StringContent, set the content type header. Need query parameters? Build the URL string yourself or wrestle with UriBuilder. Authentication? Write another extension method for your growing utilities folder.

RestSharp emerged in the early 2010s when .NET's HTTP story was fragmented across WebClient, HttpWebRequest, and eventually HttpClient. It provided what developers desperately needed: a fluent API that made REST calls feel natural. Add a parameter, set a header, execute—no ceremony. But maintaining a custom HTTP stack became untenable as .NET evolved. The v107 rewrite in 2022 acknowledged reality: HttpClient had matured into a robust foundation. Rather than compete with Microsoft's networking team, RestSharp repositioned itself as the developer experience layer that HttpClient should have been from the start.

Technical Insight

RestSharp's architecture centers on three core types: RestClient handles configuration and execution, RestRequest models what you're sending, and RestResponse wraps what comes back. The genius is in how it accumulates request details through a fluent interface before executing through the underlying HttpClient.

Here's what a typical API call looks like:

var client = new RestClient("https://api.github.com");
var request = new RestRequest("repos/{owner}/{repo}")
    .AddUrlSegment("owner", "restsharp")
    .AddUrlSegment("repo", "RestSharp")
    .AddHeader("User-Agent", "RestSharp-Demo");

var response = await client.GetAsync<GitHubRepo>(request);

if (response != null) {
    Console.WriteLine($"Stars: {response.StargazersCount}");
}

Compare this to equivalent HttpClient code, where you'd manually construct the URL, add headers to the HttpRequestMessage, handle the response stream, and deserialize JSON yourself. RestSharp collapses six operations into four fluent lines.

The v107 rewrite fundamentally changed how RestSharp manages configuration. The old model used mutable properties on RestClient itself, creating thread-safety nightmares when instances were reused. The new RestClientOptions pattern separates configuration from execution:

var options = new RestClientOptions("https://api.example.com") {
    MaxTimeout = 5000,
    ThrowOnAnyError = true,
    Authenticator = new HttpBasicAuthenticator("user", "pass")
};

var client = new RestClient(options);
// Client is now thread-safe and can be registered as singleton in DI

This design aligns with HttpClientFactory patterns while maintaining RestSharp's signature ease-of-use. The client can be registered as a singleton in dependency injection containers without the socket exhaustion issues that plagued early HttpClient usage.

Serialization flexibility is where RestSharp truly shines beyond basic HttpClient usage. The library defaults to System.Text.Json but makes swapping serializers trivial through separate NuGet packages:

// Using Newtonsoft.Json for compatibility with legacy APIs
var client = new RestClient(
    options,
    configureSerialization: s => s.UseNewtonsoftJson()
);

// Or custom XML serialization
var xmlClient = new RestClient(
    options, 
    configureSerialization: s => s.UseXmlSerializer()
);

This modular approach means you're not locked into Microsoft's serialization decisions. Projects with complex JSON requirements, legacy XML APIs, or even CSV endpoints can use the same familiar RestSharp API while swapping the underlying serialization engine.

The authentication system deserves special attention. Rather than manually managing tokens across requests, RestSharp provides authenticators that intercept requests:

public class BearerTokenAuthenticator : AuthenticatorBase {
    private readonly string _token;

    public BearerTokenAuthenticator(string token) : base(token) {
        _token = token;
    }

    protected override ValueTask<Parameter> GetAuthenticationParameter(string accessToken) {
        var parameter = new HeaderParameter(KnownHeaders.Authorization, $"Bearer {_token}");
        return new ValueTask<Parameter>(parameter);
    }
}

var authenticator = new BearerTokenAuthenticator("your-jwt-token");
var options = new RestClientOptions("https://api.example.com") {
    Authenticator = authenticator
};

This pattern cleanly separates authentication logic from business logic. Every request automatically includes proper credentials without littering your codebase with header manipulation. For OAuth flows or token refresh scenarios, you can implement custom authenticators that handle complex authentication state.

The request/response model also handles multipart form data elegantly, a common pain point when uploading files:

var request = new RestRequest("upload", Method.Post)
    .AddFile("document", "/path/to/file.pdf", "application/pdf")
    .AddParameter("description", "Quarterly report")
    .AddParameter("category", "finance");

var response = await client.ExecuteAsync(request);

RestSharp handles the multipart boundary, content disposition headers, and stream management that would require dozens of lines with raw HttpClient. This is the library at its best: making complex HTTP scenarios feel simple.

Gotcha

The v107 breaking changes created real migration pain for teams on older versions. If your codebase references IRestRequest, IRestResponse, or uses the synchronous Execute methods extensively, upgrading means refactoring across your entire HTTP layer. The library removed these interfaces entirely, not even marking them obsolete—they're just gone. Teams maintaining large applications found themselves stuck on v106 or facing a significant migration project.

RestSharp also inherits HttpClient's quirks without adding solutions. There's no built-in retry logic, circuit breakers, or timeout policies beyond basic cancellation tokens. If your API client needs resilience patterns, you're layering Polly on top of RestSharp on top of HttpClient—three abstraction layers when you might only need two. The library's single-maintainer status compounds this: the GitHub issues list shows feature requests and bugs that linger for months. Unless you're prepared to fork or contribute PRs yourself, you're dependent on one person's availability and priorities. For critical production systems, this governance model introduces risk that enterprises need to evaluate seriously.

Verdict

Use if: You're building .NET applications that consume multiple REST APIs with varying authentication schemes and data formats, and you value developer productivity over compile-time safety. RestSharp excels when you need to integrate with third-party APIs quickly, handle both JSON and XML responses, or work with file uploads and complex parameter scenarios. It's ideal for internal tools, integration projects, or any codebase where the HTTP client is a means to an end rather than the core architecture. Skip if: You're starting a new microservices project where type-safe contracts matter—Refit's interface-based approach will catch breaking API changes at compile time rather than runtime. Also skip if you need advanced resilience patterns; using HttpClient directly with Polly and HttpClientFactory gives you better control and one less dependency to manage. Finally, reconsider if your HTTP needs are simple—modern HttpClient with System.Text.Json's source generators might be all you need without adding another library to maintain.