Create a client¶

Run the complete page example.

Once you have described a service on an interface, you need an object your app can call. Refit creates that client for you. Give it the HTTP client and settings you want to use, then call the interface methods to make requests.

Start with RestService.ForGenerated<T>. It uses the implementation Refit generated for your interface and works with the generated JSON setup shown below.

Reuse your HTTP client¶

ForGenerated<T> does not switch an unsupported method to reflected request building.

1. Describe the API. The complete sample also declares methods that demonstrate authorization. Person is the model from your first request.

internal interface IClientApi
{
    [Get("/clients/person")]
    Task<Person> ReadAsync();

    [Get("/clients/authorized")]
    [Headers("Authorization: Bearer")]
    Task<Person> AuthorizedAsync();

    [Get("/clients/explicit")]
    Task<Person> ExplicitAsync([Authorize] string token);
}

2. Give Refit the JSON context. The shared context registers Person. Refit reads and writes JSON with the context's own options, and it never falls back to reflection. This is the short path. It needs no options or settings object.

3. Create the implementation. Pass httpClient, your app's shared HttpClient with its BaseAddress set. Keep the client alive for the calls that use it.

This supplied-client shape keeps the transport, handlers and fixed authentication headers in HttpClient, while ForGenerated<T> supplies only the typed Refit implementation. It is the generated path to use when trimming or Native AOT matters.

IClientApi api = RestService.ForGenerated<IClientApi>(httpClient, SampleJsonContext.Default);
Person person = await api.ReadAsync();
Console.WriteLine(person.Name); // Ada

The runnable source checks the returned person. Dispose your shared HTTP client when its owner shuts down. Creating a Refit implementation around a supplied client does not create another HTTP client. The context overloads exist on .NET 8 and later.

Use settings instead of a context¶

RefitSettings holds the serializer and every other choice for a client: headers, formatters and error handling. Pass settings when you need more than JSON, or when you prefer to own the JSON options. Pick the options way when you have JsonSerializerOptions to share, need full control, or want one options object reused elsewhere in your app. The short path needs no options object. The options way makes you assign the TypeInfoResolver yourself and keep the options unchanged after first use. Add using System.Text.Json; for JsonSerializerOptions.

private static readonly JsonSerializerOptions JsonOptions = new(SampleJsonContext.Default.Options) { TypeInfoResolver = SampleJsonContext.Default };

ForGenerated<T> takes settings built from those options in place of the context:

RefitSettings settings = new(new SystemTextJsonContentSerializer(JsonOptions));
IClientApi withSettings = RestService.ForGenerated<IClientApi>(httpClient, settings);

RefitSettings.ForJsonContext(context) is a shortcut that builds settings from a context. They use the context's own options, like the short path.

RefitSettings shortcut = RefitSettings.ForJsonContext(SampleJsonContext.Default);
IClientApi withShortcut = RestService.ForGenerated<IClientApi>(httpClient, shortcut);

When you have settings and want the context too, ForGenerated(client, context, settings) is the bridge. It keeps your settings and adds the context, so you do not assign a TypeInfoResolver by hand. It sets the result as settings.ContentSerializer. Your naming policy and converters apply. See choose whose settings apply. This example keeps a Buffered setting next to the context.

IClientApi bridged = RestService.ForGenerated<IClientApi>(httpClient, SampleJsonContext.Default, new RefitSettings { Buffered = true });

Select an interface through Type¶

Use the non-generic overload when your app selects a known interface through a Type value. It returns object, so the caller casts the implementation. Its settings parameter is required, and it has no context overload. Pass settings from above, or settings built with RefitSettings.ForJsonContext.

Type apiType = typeof(IClientApi);
object implementation = RestService.ForGenerated(apiType, httpClient, settings);
IClientApi selected = (IClientApi)implementation;

This lookup can resolve a registered generated interface without runtime generic construction. Loading unknown interface types by name is a separate reflection concern. Keep each interface and its generated implementation available in the published app.

Own a client created from a URL¶

CreateHttpClient gives you a client you can explicitly dispose. It sets BaseAddress, uses HttpMessageHandlerFactory when supplied, and installs the settings token handler.

using HttpClient client = RestService.CreateHttpClient("https://people.example", settings);
IClientApi api = RestService.ForGenerated<IClientApi>(client, settings);
Person person = await api.ReadAsync();

The string overloads of ForGenerated, with or without a context, create their own HTTP client. For an interface that inherits IDisposable, the generated implementation disposes that client. Use that interface only when you want it to own the transport.

internal interface IOwnedClientApi : IClientApi, IDisposable;

const string baseUrl = "https://people.example";
using IOwnedClientApi owned = RestService.ForGenerated<IOwnedClientApi>(baseUrl, settings);
using IOwnedClientApi contextOwned = RestService.ForGenerated<IOwnedClientApi>(baseUrl, SampleJsonContext.Default);
using IOwnedClientApi defaultOwned = RestService.ForGenerated<IOwnedClientApi>(baseUrl);
using IOwnedClientApi selectedOwned = (IOwnedClientApi)RestService.ForGenerated(typeof(IOwnedClientApi), baseUrl, settings);

Disposing such an implementation also disposes a supplied HTTP client. Use an ordinary interface for clients that share a transport owned elsewhere. Prefer an explicitly owned HttpClient when the API interface does not expose disposal.

CreateHttpClient rejects a null, empty or whitespace URL. An invalid base address fails URI validation. Its settings parameter can be null. Legacy URL resolution trims trailing slashes; RFC resolution preserves them. See URL resolution settings.

Choose the reflection path when needed¶

RestService.For supports interfaces whose methods need runtime request building. Install Refit.Reflection for that fallback. This path uses reflection to inspect metadata and can require runtime generic compilation. It is unsuitable as a Native AOT fallback.

IClientApi reflected = RestService.For<IClientApi>(httpClient, settings);
IRequestBuilder<IClientApi> builder = RequestBuilder.ForType<IClientApi>(settings);
IClientApi suppliedBuilder = RestService.For(httpClient, builder);
object runtimeSelected = RestService.For(typeof(IClientApi), httpClient, builder);

The settings overload first tries a fully inline generated implementation. If that is unavailable, it creates a reflected request builder. The supplied-builder overload uses the builder you provide. All For overloads carry trimming warnings because their fallback needs runtime metadata. See request builders for selecting reflected methods.

Creation overloads¶

Each row describes one public overload. The ForGenerated overloads use only source-generated implementations. The For overloads can create a reflected request builder when an inline generated implementation is unavailable.

Production implementations: RestService.cs, RequestBuilder.cs, and IRequestBuilder.cs.

Generic overloads without settings or a context use defaults. Those defaults do not register your JSON models for AOT. Pass a context, or settings that hold generated serializer metadata, for calls that serialize or read models. Generated overloads that take settings reject null settings and null clients. An unavailable generated implementation throws InvalidOperationException. An unsupported generated method throws instead of using reflected fallback. Fix the RF006 warning before using that method through generated-only creation. Find methods that fall back to reflection explains each reason and how to make the build fail on one.

On .NET Framework, generated registration differs because module initializers are unavailable. Refit can resolve the emitted implementation type by name and construct it through reflection. The generated-only request builder still rejects reflected method fallback. The modern .NET examples avoid that type-name construction path.