Refit — Type-Safe REST Client for .NET

Introduction

Refit is a type-safe REST client library for .NET inspired by Retrofit for Android. You define an interface describing your API endpoints, and Refit generates the implementation at compile time using source generators, turning HTTP calls into simple method invocations.

What Refit Does

• Generates HTTP client implementations from annotated C# interfaces
• Maps method parameters to URL segments, query strings, headers, and body content
• Serializes request bodies and deserializes responses automatically
• Integrates with HttpClientFactory for connection pooling and lifecycle management
• Supports multipart uploads, streaming, and generic API response wrappers

Architecture Overview

Refit uses C# source generators to analyze interface definitions at compile time and emit concrete HttpClient-based implementations. Each method attribute ([Get], [Post], etc.) maps to an HTTP verb, and parameter attributes control where values are placed in the request. At runtime, the generated code uses HttpClient directly, avoiding reflection overhead. Serialization defaults to System.Text.Json with Newtonsoft.Json available as an option.

Self-Hosting & Configuration

• Install via NuGet: dotnet add package Refit.HttpClientFactory
• Define API interfaces with HTTP method attributes and route templates
• Register with DI: builder.Services.AddRefitClient<IMyApi>()
• Configure base address, default headers, and timeout via HttpClient options
• Compatible with .NET 6 through .NET 9

Key Features

• Compile-time source generation with no runtime reflection
• Automatic parameter serialization for URL, query, header, and body
• Support for ApiResponse wrapper with status code and headers access
• Multipart file upload via StreamPart and ByteArrayPart
• Dynamic header injection through [HeaderCollection] and [Authorize]

Comparison with Similar Tools

• RestSharp — fluent HTTP client; more manual, no interface-based generation
• HttpClient (raw) — built-in .NET HTTP; full control but verbose boilerplate
• Flurl — fluent URL and HTTP builder; convenient but no compile-time type safety
• RestEase — similar interface-driven approach; uses runtime proxy generation instead of source gen
• NSwag/OpenAPI Generator — generates clients from OpenAPI specs; different workflow, spec-first

FAQ

Q: Does Refit use reflection at runtime? A: No. Since version 6, Refit uses compile-time source generators to create implementations, avoiding reflection entirely.

Q: Can I add authentication headers to all requests? A: Yes. Use the [Headers] attribute on the interface for static headers, or configure a DelegatingHandler that adds bearer tokens dynamically via HttpClientFactory.

Q: How do I handle error responses? A: Return ApiResponse instead of T. This wrapper includes the HTTP status code, headers, and error content, allowing you to handle non-success responses without exceptions.

Q: Can I use Refit with Polly for resilience? A: Yes. When registering the Refit client via AddRefitClient, chain AddStandardResilienceHandler() from Microsoft.Extensions.Http.Resilience to add retry and circuit breaker policies.

Sources

• https://github.com/reactiveui/refit
• https://reactiveui.github.io/refit/