Refit: turning a C# interface into an HTTP client

The problem Refit solves for .NET teams

Hand-written HTTP code in .NET drifts. A URL string changes on the server, the call site keeps compiling, and the mismatch shows up as a 404 in production. Refit moves that contract into a C# interface: attributes describe the request method, URL, headers and body, and the source generator builds the implementation when your app compiles. The README's framing is that Refit turns a C# interface into an HTTP client, and that your app keeps control of HttpClient, cancellation and serialization. That last part matters. Refit is not a networking stack of its own; it is a code generator plus request-building conventions layered over the HttpClient you already configure. The audience is .NET developers who call a known REST API from several places and want one typed entry point instead of repeated HttpClient boilerplate. The package split reflects that: Refit carries the generated clients, request attributes, serializers and response types, including the generator, interface analyzers and code fixes.

How the source generator builds the client

The mechanism is compile-time code generation, not runtime proxying. You declare an interface, annotate methods with HTTP verb and route attributes, and the generator emits the implementation during the build. Because the implementation is ordinary generated C#, the compiler checks your call sites against it, and the interface analyzers can flag mistakes in how the interface itself is written. The README also lists Refit.Reflection as an optional path that builds requests through runtime reflection, and it is explicit about the trade-off: generated clients are the recommendation for trimmed and Native AOT apps, where reflection-based request building is the thing you are trying to avoid. Serialization is pluggable rather than fixed. System.Text.Json with generated metadata is described as the preferred JSON setup, with Refit.Newtonsoft.Json and Refit.Xml available as separate packages when you need Newtonsoft.Json or XML content. Return types are not limited to Task<T>. The documentation covers ValueTask<T>, IObservable<T>, IAsyncEnumerable<T>, response wrappers and custom return adapters, plus streaming for JSON arrays, JSON Lines and server-sent events. Errors have their own surface: HTTP, transport and deserialization failures, typed error content and problem details, with the ability to enforce success and redact sensitive details. Refit.Testing exists to match outgoing requests, supply local replies, verify calls and simulate network faults, which is how the request layer gets exercised without a live server.

What Refit ships and where to get it

Refit is distributed as NuGet packages, and the README's packages table is the map. The core package, Refit, carries the generated HTTP clients, request attributes, serializers and response types, and it includes the generator, interface analyzers and code fixes. Refit.HttpClientFactory adds registration with dependency injection and IHttpClientFactory, covering generated-only and keyed registrations. Refit.Testing matches outgoing requests, supplies local replies, verifies calls and simulates network faults. Refit.Newtonsoft.Json serializes content with Newtonsoft.Json, and Refit.Xml serializes XML content. Refit.Reflection is the optional request-building path through runtime reflection. The README points to the Refit documentation for concepts and a walkthrough of a first request, and to the source examples under src/examples/Documentation for runnable code. Those examples use .NET 10 and C# 14 unless they state another target, and the README warns that website code blocks can show a subset of a complete example and omit its test setup. The README does not print an install command, so the first step is to add the package you need from that table through your normal NuGet workflow. The choice that matters is serialization: System.Text.Json with generated metadata is the preferred JSON setup, with the JSON configuration and AOT guidance pages covering the metadata side.

Where Refit gets in the way

The compile-time contract is also the constraint. If your endpoints are discovered at runtime, loaded from configuration, or vary per tenant in ways the interface cannot express, the generated-client path does not fit, and Refit.Reflection is the escape hatch the README describes as optional and as the non-recommended option for trimmed and Native AOT apps. Refit also does not hide HttpClient from you, and that is deliberate: the README says your app keeps control of HttpClient, cancellation and serialization. The consequence is that handler configuration, timeouts and transport behavior remain your responsibility, documented under settings and request metadata rather than solved for you. Serialization is another boundary. The preferred JSON setup is System.Text.Json with generated metadata, so projects standardized on Newtonsoft.Json must add a package and accept a second serializer in the dependency graph. Finally, the README points at a page of known behavior discrepancies recorded beside the affected APIs. That page existing at all is a signal worth reading before you adopt: some documented behaviors differ from what a reader might assume. The README does not document rollback or migration steps between major versions, so plan upgrades from the release notes rather than from the README.

Refit compared with hand-written HttpClient code

The honest alternative is the code you would write without Refit: an HttpClient, a base address, and a method per endpoint that builds a URL, sends the request and deserializes the response. The README links a why use Refit page that shows equivalent manual HTTP code and trade-offs, which is the right place to compare, because the difference is not capability. Both approaches use the same transport. The difference is where the contract lives. Manual code puts route strings and serialization calls at each call site, so the compiler cannot tell you that a path changed. Refit puts them in an interface that the generator implements, so the same mistake becomes a build error. The cost is a generator in your build, a set of attributes to learn, and a package decision for serialization and DI. Manual code has no generator, no attribute vocabulary and no package split, and it stays viable when endpoints are dynamic. A second real alternative is a runtime-reflection client, which Refit itself offers as Refit.Reflection; it trades compile-time generation for runtime request building, which is exactly the trade the AOT guidance warns about.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-21. The recent release list shows v16.1.0 on 2026-09-21, v16.0.0 on 2026-09-20 and v15.2.0 on 2026-08-18, so the project is releasing frequently, including a major version bump between v15 and v16. That cadence is the main upgrade cost: a major version is where behavior changes land, and the README does not describe a migration path. The website's known behavior discrepancies page is the closest thing to a compatibility reference available. Refit is MIT licensed, which is permissive and places few conditions on redistribution and modification; the LICENSE and COPYING files sit at the repository root. This is not legal advice, and the licence text is what governs. Operationally, the packages are versioned together, so a project pulling Refit, Refit.HttpClientFactory and a serializer package has three version lines to keep aligned. The build task and the repository's analyzer and code-fix components mean the generator participates in your compilation, so a toolchain upgrade can surface new diagnostics. Budget for that on major releases rather than treating Refit as a silent dependency.

Editorial conclusion

Adopt Refit when your REST surface is known at compile time and you want the interface to be the contract, especially in trimmed or Native AOT apps where the generated client is the supported path. Skip it when endpoints are configured at runtime, since Refit.Reflection is the optional fallback and the README points generated clients at trimmed and AOT builds. Before committing, verify which package set you need (Refit alone, plus Refit.HttpClientFactory for DI registration, plus a serializer such as Refit.Newtonsoft.Json or Refit.Xml), and check the website's known behavior discrepancies beside the APIs you plan to call.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. reactiveui/refit on GitHub
4. README
5. Releases