Pathoschild.Http.FluentClient 4.3.0

dotnet add package Pathoschild.Http.FluentClient --version 4.3.0
NuGet\Install-Package Pathoschild.Http.FluentClient -Version 4.3.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Pathoschild.Http.FluentClient" Version="4.3.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Pathoschild.Http.FluentClient --version 4.3.0
#r "nuget: Pathoschild.Http.FluentClient, 4.3.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Pathoschild.Http.FluentClient as a Cake Addin
#addin nuget:?package=Pathoschild.Http.FluentClient&version=4.3.0

// Install Pathoschild.Http.FluentClient as a Cake Tool
#tool nuget:?package=Pathoschild.Http.FluentClient&version=4.3.0

FluentHttpClient is a modern async HTTP client for REST APIs. Its fluent interface lets you send an HTTP request and parse the response in one go — hiding away the gritty details like deserialisation, content negotiation, optional retry logic, and URL encoding:

Blog result = await new FluentClient("https://example.org/api")
   .GetAsync("blogs")
   .WithArgument("id", 15)
   .WithBearerAuthentication(token)
   .As<Blog>();

Designed with discoverability and extensibility as core principles, just autocomplete to see which methods are available at each step.

Contents

Get started

Install

Install it from NuGet:

Install-Package Pathoschild.Http.FluentClient

The client works on most platforms (including Linux, Mac, and Windows):

platform min version
.NET 5.0
.NET Core 1.0
.NET Framework 4.5.2
.NET Standard 1.3
Mono 4.6
Unity 2018.1
Universal Windows Platform 10.0
Xamarin.Android 7.0
Xamarin.iOS 10.0
Xamarin.Mac 3.0

Basic usage

Just create the client and chain methods to set up the request/response. For example, this sends a GET request and deserializes the response into a custom Item class based on content negotiation:

Item item = await new FluentClient()
   .GetAsync("https://example.org/api/items/14")
   .As<Item>();

You can also reuse the client for many requests (which improves performance using the built-in connection pool), and set a base URL in the constructor:

using var client = new FluentClient("https://example.org/api");

Item item = await client
   .GetAsync("items/14")
   .As<Item>();

The client provides methods for DELETE, GET, POST, PUT, and PATCH out of the box. You can also use SendAsync to craft a custom HTTP request.

URL arguments

You can add any number of arguments to the request URL with an anonymous object:

await client
   .PostAsync("items/14")
   .WithArguments(new { page = 1, search = "some search text" });

Or with a dictionary:

await client
   .PostAsync("items/14")
   .WithArguments(new Dictionary<string, object> { … });

Or individually:

await client
   .PostAsync("items/14")
   .WithArgument("page", 1)
   .WithArgument("search", "some search text");

Body

You can add a model body directly in a POST or PUT:

await client.PostAsync("search", new SearchOptions(…));

Or add it to any request:

await client
   .GetAsync("search")
   .WithBody(new SearchOptions(…));

Or provide it in various formats:

format example
serialized model WithBody(new ExampleModel())
form URL encoded WithBody(p => p.FormUrlEncoded(values))
file upload WithBody(p => p.FileUpload(files))
HttpContent WithBody(httpContent)

Headers

You can add any number of headers:

await client
   .PostAsync("items/14")
   .WithHeader("User-Agent", "Some Bot/1.0.0")
   .WithHeader("Content-Type", "application/json");

Or use methods for common headers like WithAuthentication, WithBasicAuthentication, WithBearerAuthentication, and SetUserAgent.

(Basic headers like Content-Type and User-Agent will be added automatically if you omit them.)

Read the response

You can parse the response by awaiting an As* method:

await client
   .GetAsync("items")
   .AsArray<Item>();

Here are the available formats:

type method
Item As<Item>()
Item[] AsArray<Item>()
byte[] AsByteArray()
string AsString()
Stream AsStream()
JToken AsRawJson()
JObject AsRawJsonObject()
JArray AsRawJsonArray()

The AsRawJson method can also return dynamic to avoid needing a model class:

dynamic item = await client
   .GetAsync("items/14")
   .AsRawJsonObject();

string author = item.Author.Name;

If you don't need the content, you can just await the request:

await client.PostAsync("items", new Item(…));

Handle errors

By default the client will throw ApiException if the server returns an error code:

try
{
   await client.Get("items");
}
catch(ApiException ex)
{
   string responseText = await ex.Response.AsString();
   throw new Exception($"The API responded with HTTP {ex.Response.Status}: {responseText}");
}

If you don't want that, you can...

  • disable it for one request:

    IResponse response = await client
       .GetAsync("items")
       .WithOptions(ignoreHttpErrors: true);
    
  • disable it for all requests:

    client.SetOptions(ignoreHttpErrors: true);
    
  • use your own error filter.

Advanced features

Response metadata

The previous examples parse the response directly, but sometimes you want to peek at the HTTP metadata:

IResponse response = await client.GetAsync("messages/latest");
if (response.IsSuccessStatusCode || response.Status == HttpStatusCode.Found)
   return response.AsArray<T>();

Simple retry policy

The client won't retry failed requests by default, but that's easy to configure:

client
   .SetRequestCoordinator(
      maxRetries: 3,
      shouldRetry: request => request.StatusCode != HttpStatusCode.OK,
      getDelay: (attempt, response) => TimeSpan.FromSeconds(attempt * 5) // wait 5, 10, and 15 seconds
   );

Chained retry policies

You can also wrap retry logic into IRetryConfig implementations:

/// <summary>A retry policy which retries with incremental backoff.</summary>
public class RetryWithBackoffConfig : IRetryConfig
{
    /// <summary>The maximum number of times to retry a request before failing.</summary>
    public int MaxRetries => 3;

    /// <summary>Get whether a request should be retried.</summary>
    /// <param name="response">The last HTTP response received.</param>
    public bool ShouldRetry(HttpResponseMessage response)
    {
        return request.StatusCode != HttpStatusCode.OK;
    }

    /// <summary>Get the time to wait until the next retry.</summary>
    /// <param name="attempt">The retry index (starting at 1).</param>
    /// <param name="response">The last HTTP response received.</param>
    public TimeSpan GetDelay(int attempt, HttpResponseMessage response)
    {
        return TimeSpan.FromSeconds(attempt * 5); // wait 5, 10, and 15 seconds
    }
}

Then you can add one or more retry policies, and they'll each be given the opportunity to retry a request:

client
   .SetRequestCoordinator(new[]
   {
      new TokenExpiredRetryConfig(),
      new DatabaseTimeoutRetryConfig(),
      new RetryWithBackoffConfig()
   });

Note that there's one retry count across all retry policies. For example, if TokenExpiredRetryConfig retries once before falling back to RetryWithBackoffConfig, the latter will receive 2 as its first retry count. If you need more granular control, see custom retry/coordination policy.

Cancellation tokens

The client fully supports .NET cancellation tokens if you need to cancel requests:

using var tokenSource = new CancellationTokenSource();

await client
   .PostAsync(…)
   .WithCancellationToken(tokenSource.Token);

tokenSource.Cancel();

The cancellation token is used for the whole process, from sending the request to reading the response. You can change the cancellation token on the response if needed, by awaiting the request and calling WithCancellationToken on the response.

Custom requests

You can make changes directly to the HTTP request before it's sent:

client
   .GetAsync("items")
   .WithCustom(request =>
   {
      request.Method = HttpMethod.Post;
      request.Headers.CacheControl = new CacheControlHeaderValue { MaxAge = TimeSpan.FromMinutes(30) };
   });

Synchronous use

The client is built around the async and await keywords, but you can use the client synchronously. That's not recommended — it complicates error-handling (e.g. errors get wrapped into AggregateException), and it's very easy to cause thread deadlocks when you do this (see Parallel Programming with .NET: Await, and UI, and deadlocks! Oh my! and Don't Block on Async Code).

If you really need to use it synchronously, you can just call the Result property:

Item item = client.GetAsync("items/14").Result;

Or if you don't need the response:

client.PostAsync("items", new Item(…)).AsResponse().Wait();

Extensibility

Custom formats

The client supports JSON and XML out of the box. If you need more, you can...

  • Add any of the existing media type formatters:

    client.Formatters.Add(new YamlFormatter());
    
  • Create your own by subclassing MediaTypeFormatter (optionally using the included MediaTypeFormatterBase class).

Custom filters

You can read and change the underlying HTTP requests and responses by creating IHttpFilter implementations. They can be useful for automating custom authentication or error-handling.

For example, the default error-handling is just a filter:

/// <summary>Method invoked just after the HTTP response is received. This method can modify the incoming HTTP response.</summary>
/// <param name="response">The HTTP response.</param>
/// <param name="httpErrorAsException">Whether HTTP error responses (e.g. HTTP 404) should be raised as exceptions.</param>
public void OnResponse(IResponse response, bool httpErrorAsException)
{
   if (httpErrorAsException && !response.Message.IsSuccessStatusCode)
      throw new ApiException(response, $"The API query failed with status code {response.Message.StatusCode}: {response.Message.ReasonPhrase}");
}

...which you can replace with your own:

client.Filters.Remove<DefaultErrorFilter>();
client.Filters.Add(new YourErrorFilter());

You can do much more with HTTP filters by editing the requests before they're sent or the responses before they're parsed:

/// <summary>Method invoked just before the HTTP request is submitted. This method can modify the outgoing HTTP request.</summary>
/// <param name="request">The HTTP request.</param>
public void OnRequest(IRequest request)
{
   // example only — you'd normally use a method like client.SetAuthentication(…) instead.
   request.Message.Headers.Authorization = new AuthenticationHeaderValue("token", "…");
}

Custom retry/coordination policy

You can implement IRequestCoordinator to control how requests are dispatched. For example, here's a retry coordinator using Polly:

/// <summary>A request coordinator which retries failed requests with a delay between each attempt.</summary>
public class RetryCoordinator : IRequestCoordinator
{
   /// <summary>Dispatch an HTTP request.</summary>
   /// <param name="request">The response message to validate.</param>
   /// <param name="send">Dispatcher that executes the request.</param>
   /// <returns>The final HTTP response.</returns>
   public Task<HttpResponseMessage> ExecuteAsync(IRequest request, Func<IRequest, Task<HttpResponseMessage>> send)
   {
      HttpStatusCode[] retryCodes = { HttpStatusCode.GatewayTimeout, HttpStatusCode.RequestTimeout };
      return Policy
         .HandleResult<HttpResponseMessage>(request => retryCodes.Contains(request.StatusCode)) // should we retry?
         .WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(attempt)) // up to 3 retries with increasing delay
         .ExecuteAsync(() => send(request)); // begin handling request
   }
}

...and here's how you'd set it:

client.SetRequestCoordinator(new RetryCoordinator());

(You can only have one request coordinator on the client; you should use HTTP filters instead for most overrides.)

Custom HTTP

For advanced scenarios, you can customise the underlying HttpClient and HttpClientHandler. See the next section for an example.

Mocks for unit testing

Here's how to create mock requests for unit testing using RichardSzalay.MockHttp:

// create mock
var mockHandler = new MockHttpMessageHandler();
mockHandler.When(HttpMethod.Get, "https://example.org/api/items").Respond(HttpStatusCode.OK, testRequest => new StringContent("[]"));

// create client
var client = new FluentClient("https://example.org/api", new HttpClient(mockHandler));
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard1.3 is compatible.  netstandard1.4 was computed.  netstandard1.5 was computed.  netstandard1.6 was computed.  netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net452 is compatible.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap was computed.  uap10.0 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (14)

Showing the top 5 NuGet packages that depend on Pathoschild.Http.FluentClient:

Package Downloads
StrongGrid

StrongGrid is a strongly typed .NET client for SendGrid's v3 API.

ZoomNet

ZoomNet is a strongly typed .NET client for Zoom's API.

CakeMail.RestClient

CakeMail.RestClient is a .NET wrapper for the CakeMail API

Pathoschild.FluentNexus

A modern async HTTP client for the Nexus Mods API. It gives you simple strongly-typed methods to access all of the Nexus API endpoints, handling the gritty details like deserialisation, content negotiation, URL encoding, and error-handling.

Balcony.Framework

Balcony's Framework

GitHub repositories (4)

Showing the top 4 popular GitHub repositories that depend on Pathoschild.Http.FluentClient:

Repository Stars
Pathoschild/SMAPI
The modding API for Stardew Valley.
Nexus-Mods/Nexus-Mod-Manager
qwqcode/Nacollector
Nacollector WEB data collection platform.
Jericho/StrongGrid
Strongly typed library for the entire SendGrid v3 API, including webhooks
Version Downloads Last updated
4.3.0 211,119 3/14/2023
4.2.0 238,093 10/7/2022
4.1.1 64,775 6/23/2022
4.1.0 787,904 3/11/2021
4.0.0 573,570 5/14/2020
3.3.1 261,804 7/20/2019
3.3.0 175,239 4/28/2019
3.2.0 513,953 4/18/2018
3.1.0 51,866 9/19/2017
3.0.0 57,613 2/9/2017
2.3.0 1,833 12/12/2016
2.2.0 12,363 6/30/2016
2.1.0 1,800 5/8/2016
2.0.0 1,657 4/28/2016
1.2.1 3,311 10/28/2015
1.2.0 8,534 10/30/2013
1.1.0 3,361 8/28/2013
1.0.0 3,003 11/30/2012
0.5.0-beta 1,691 10/4/2012
0.4.0-alpha6 1,595 8/29/2012
0.4.0-alpha5 1,566 8/29/2012
0.4.0-alpha4 1,580 8/28/2012
0.3.5-alpha4 1,524 8/8/2012
0.3.4-alpha 1,556 8/7/2012
0.3.3-alpha 1,562 8/7/2012
0.3.2-alpha 1,558 7/20/2012
0.3.1-alpha 1,590 7/17/2012
0.3.0-alpha 1,541 6/25/2012
0.2.0-alpha 1,591 6/5/2012
0.1.5-alpha 1,636 5/29/2012
0.1.4-alpha 1,609 5/24/2012
0.1.3-alpha 1,611 5/24/2012
0.1.2-alpha 1,644 5/23/2012