Static Typing and Typed Clients

Since version 4.0 RestClient supports full static typing - the most requested feature since RestClient was released. Static typing is 100% backwards compatible - all the dynamic syntax you know and love works exactly as before, just declare your client as dynamic as usual.

To use static typing declare your client as RestClient or var instead of dynamic - and you get full IntelliSense.

The Resource method

The Resource method takes a string representing the resource you want to access, then you end with the HTTP method you want to use, exactly the same as the dynamic syntax.

var client = new RestClient("https://jsonplaceholder.typicode.com");

User user = await client.Resource("users/1").Get();

You can chain Resource calls if you prefer:

var client = new RestClient("https://jsonplaceholder.typicode.com");

User user = await client.Resource("users").Resource("1").Get();

Typed responses

The HTTP methods return dynamic, which supports implicit casting to your static type as shown above. If you prefer to be explicit use the generic overloads:

var client = new RestClient("https://jsonplaceholder.typicode.com");

var user = await client.Resource("users/1").Get<User>();

var users = await client.Resource("users").Get<List<User>>();

The mutable methods take a typed body and can return a typed response too:

var client = new RestClient("https://jsonplaceholder.typicode.com");

User createdUser = await client.Resource("users").Post(new User { Name = "foo" });

// Or explicitly
var createdUser = await client.Resource("users").Post<User, User>(new User { Name = "foo" });

HttpClient Typed Clients

RestClient works with ASP.NET Core’s Typed Clients - the AddHttpClient<TClient>() pattern - letting you create maintainable SDK style clients for your domain, with all the IHttpClientFactory goodness (handler pooling, Polly policies etc.) you get from AddHttpClient.

Your typed client takes the HttpClient injected by IHttpClientFactory and wraps it in a RestClient using HttpClientWrapper:

using DalSoft.RestClient;

public class GitHubClient
{
   private readonly RestClient _restClient;

   public GitHubClient(HttpClient httpClient)
   {
      _restClient = new RestClient(
         new HttpClientWrapper(httpClient, new Headers(new { UserAgent = "MyClient" })),
         "https://api.github.com");
   }

   public async Task<List<Repository>> GetRepositories(string user)
   {
      return await _restClient.Resource($"users/{user}/repos").Get<List<Repository>>();
   }
}

Register your typed client using AddHttpClient<TClient>() as you would any typed client - adding the DefaultJsonHandler to the pipeline, which is what gives RestClient its JSON binding:

using DalSoft.RestClient;
using DalSoft.RestClient.Handlers;

public void ConfigureServices(IServiceCollection services)
{
   services.AddHttpClient<GitHubClient>()
           .AddHttpMessageHandler(() => new DefaultJsonHandler(new Config()));
}

Then just inject your typed client wherever you need it:

public class GitHubController : Controller
{
   private readonly GitHubClient _gitHubClient;

   public GitHubController(GitHubClient gitHubClient)
   {
      _gitHubClient = gitHubClient;
   }

   [Route("github/users/dalsoft"), HttpGet]
   public async Task<List<Repository>> GetRepositories()
   {
      return await _gitHubClient.GetRepositories("dalsoft");
   }
}

If you don’t need a typed client, IRestClientFactory is the simplest way to use RestClient with IHttpClientFactory.

Headers, Query Strings and everything else

Headers and query strings work with static typing exactly the same as the dynamic syntax:

var client = new RestClient("https://jsonplaceholder.typicode.com");

var users = await client
   .Headers(new { CacheControl = "no-cache" })
   .Resource("users")
   .Query(new { id = 2 })
   .Get<List<User>>();

Authorization

Version 4.0 added the Authorization method supporting the Bearer and Basic schemes, which sets the Authorization header for you.

Bearer scheme:

var client = new RestClient("https://api.github.com");

var repositories = await client
   .Authorization(AuthenticationSchemes.Bearer, "your-token")
   .Resource("users/dalsoft/repos")
   .Get();

Basic scheme - pass the username and password and RestClient will Base64 encode the header for you:

var client = new RestClient("https://api.example.com");

var result = await client
   .Authorization(AuthenticationSchemes.Basic, "username", "password")
   .Resource("users")
   .Get();

AuthenticationSchemes is in the DalSoft.RestClient namespace.

Passthrough HttpClient

RestClient is a lightweight wrapper around HttpClient - and since version 4.0 you can access the underlying HttpClient directly whenever you need it, either via the HttpClient property or by casting.

var client = new RestClient("https://jsonplaceholder.typicode.com");

HttpClient httpClient = client.HttpClient;

If your client is declared as dynamic you can also cast it:

dynamic client = new RestClient("https://jsonplaceholder.typicode.com");

var httpClient = (HttpClient)client;

Anything you configure via Config and the Handler Pipeline applies to the passthrough HttpClient too - you lose nothing by dropping down to the metal.

Updated: