Refit Documentation

Refit is compatible with the following platforms and .NET targets:

• WinUI
• Desktop .NET Framework 4.6.2+
• .NET 8 / 9 / 10 / 11
• Blazor
• Uno Platform

Refit has first-class support for IHttpClientFactory. To use it, add a reference to Refit.HttpClientFactory and use the AddRefitClient<T> extension method in your service configuration.

// Basic configuration
services.AddRefitClient<IWebApi>()
        .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"));

// Configuration with RefitSettings
var settings = new RefitSettings();
// Configure refit settings here

services.AddRefitClient<IWebApi>(settings)
        .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"))
        .AddHttpMessageHandler<MyHandler>();

To use Newtonsoft.Json instead of the default System.Text.Json, add the Refit.Newtonsoft.Json package and pass a NewtonsoftJsonContentSerializer to RefitSettings. You can customize behavior by providing JsonSerializerSettings to the constructor or by setting global JsonConvert.DefaultSettings.

// Basic usage
var settings = new RefitSettings(new NewtonsoftJsonContentSerializer());

// Custom settings per API
var gitHubApi = RestService.For<IGitHubApi>("https://api.github.com",
    new RefitSettings {
        ContentSerializer = new NewtonsoftJsonContentSerializer(
            new JsonSerializerSettings {
                ContractResolver = new SnakeCasePropertyNamesContractResolver()
            })
    });

When using Refit.HttpClientFactory, you can resolve tokens from the DI container using AddAuthorizationHeaderValueProvider. This is useful for per-request isolation. The provider receives an IServiceProvider, the HttpRequestMessage, and a CancellationToken.

services.AddRefitClient<IMyApi>()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"))
    .AddAuthorizationHeaderValueProvider((serviceProvider, request, cancellationToken) =>
    {
        var tokenService = serviceProvider.GetRequiredService<IMyTokenService>();
        return new ValueTask<string>(tokenService.GetTokenForCurrentRequest());
    });

To avoid reflection-based registration in Native AoT or trimmed applications, use AddRefitGeneratedClient<T> from Refit.HttpClientFactory. This ensures the application uses RestService.ForGenerated<T> and throws an InvalidOperationException if a generated client is missing, rather than silently falling back to reflection.

// Standard registration
services.AddRefitGeneratedClient<IWebApi>()
        .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"));

// Registration with settings and custom name
services.AddRefitGeneratedClient<IWebApi>(settings, "my-named-client");

Routes in a StubHttp are consumed in the order they are declared. This allows you to simulate a sequence of responses for the same endpoint.

Use Reusable = true in a RouteMatcher for routes that should match any number of requests without being required by VerifyAllCalled. One-shot routes always take priority over reusable ones.

// Sequenced responses
var http = new StubHttp
{
    { Route.Get("/status"), Reply.Json("{\"state\":\"pending\"}") },
    { Route.Get("/status"), Reply.Json("{\"state\":\"done\"}") },
};

// Reusable catch-all route
var http = new StubHttp
{
    { new RouteMatcher { Template = "*", Reusable = true }, Reply.Status(HttpStatusCode.OK) },
};

To test your Refit clients without a live server or a general-purpose mocking library, install the Refit.Testing package. This package allows you to define a route table of expected requests and their corresponding replies.

dotnet add package Refit.Testing

To send data as application/x-www-form-urlencoded, use the [Body(BodySerializationMethod.UrlEncoded)] attribute. You can pass an IDictionary<string, object> or a plain object. If using an object, all public, readable properties will be serialized as form fields. Use [AliasAs("name")] to map property names to specific form field keys.

public interface IMeasurementProtocolApi
{
    [Post("/collect")]
    Task Collect([Body(BodySerializationMethod.UrlEncoded)] Measurement measurement);
}

public class Measurement
{
    public int v { get { return 1; } }

    [AliasAs("tid")]
    public string WebPropertyId { get; set; }

    [AliasAs("cid")]
    public Guid ClientId { get; set; }

    [AliasAs("t")]
    public string Type { get; set; }
}

Run the generate-publicapi script to update the public API baseline files. You can run it for all tracked libraries or provide an optional case-sensitive substring to filter by project path (e.g., to target a specific library).

When to run:

• After changing any public (or protected on a public type) API.
• After adding a new target framework to a tracked library.
• After bumping an analyzer package that changes how the public surface is rendered.

### Linux / macOS
```bash
tools/generate-publicapi.sh                 # all tracked libraries, all TFMs
tools/generate-publicapi.sh HttpClient      # only projects whose path contains 'HttpClient'
tools/generate-publicapi.sh Refit.Xml

Windows (PowerShell)

./tools/generate-publicapi.ps1                     # all tracked libraries
./tools/generate-publicapi.ps1 -Filter HttpClient  # path filter