refit
/refit
USE FOR: Defining type-safe HTTP API clients using interfaces and attributes with Refit's source generator. Use when consuming REST APIs where compile-time safety, automatic serialization, and integration with HttpClientFactory and DI are needed. DO NOT USE FOR: Low-level HTTP operations requiring manual stream control (use HttpClient directly), GraphQL clients (use StrawberryShake or GraphQL.Client), or file download/upload with custom progress reporting (use HttpClient with stream copying).
- Author
- Tyler-R-Kendrick ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 09.06.2026
Assessment and security
- Files in this package
- 21
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 5
No signals detected. Repository changed on 09.06.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
USE FOR: Defining type-safe HTTP API clients using interfaces and attributes with Refit's source generator. Use when consuming REST APIs where compile-time safety, automatic serialization, and integration with HttpClientFactory and DI are needed. DO NOT USE FOR: Low-level HTTP operations requiring manual stream control (use HttpClient directly), GraphQL clients (use StrawberryShake or GraphQL.Client), or file download/upload with custom progress reporting (use HttpClient with stream copying).
Original author description
USE FOR: Defining type-safe HTTP API clients using interfaces and attributes with Refit's source generator. Use when consuming REST APIs where compile-time safety, automatic serialization, and integration with HttpClientFactory and DI are needed. DO NOT USE FOR: Low-level HTTP operations requiring manual stream control (use HttpClient directly), GraphQL clients (use StrawberryShake or GraphQL.Client), or file download/upload with custom progress reporting (use HttpClient with stream copying).
How it works
- Overview
- Defining API Interfaces
- ASP.NET Core Registration with HttpClientFactory
- Authentication with Delegating Handlers
- Error Handling with ApiException
- Headers and Dynamic Configuration
- Refit vs Other HTTP Client Libraries
- Best Practices
SKILL.md preview
---
name: refit
description: |
USE FOR: Defining type-safe HTTP API clients using interfaces and attributes with Refit's source generator. Use when consuming REST APIs where compile-time safety, automatic serialization, and integration with HttpClientFactory and DI are needed.
DO NOT USE FOR: Low-level HTTP operations requiring manual stream control (use HttpClient directly), GraphQL clients (use StrawberryShake or GraphQL.Client), or file download/upload with custom progress reporting (use HttpClient with stream copying).
license: MIT
metadata:
displayName: Refit
author: "Tyler-R-Kendrick"
version: "1.0.0"
compatibility:
- claude
- copilot
- cursor
references:
- title: "Refit GitHub Repository"
url: "https://github.com/reactiveui/refit"
- title: "Refit NuGet Package"
url: "https://www.nuget.org/packages/Refit"
---
# Refit
## Overview
Refit is a type-safe REST client library for .NET that turns interface definitions into live HTTP clients using source generators. You define an interface with attributes like `[Get]`, `[Post]`, `[Put]`, and `[Delete]` on methods, and Refit generates the implementation at compile time. Refit handles URL interpolation, query string building, JSON serialization/deserialization, multipart uploads, and header management. It integrates with `HttpClientFactory` for proper handler lifecycle management and with ASP.NET Core's dependency injection for clean service registration. Refit uses `System.Text.Json` by default and supports `Newtonsoft.Json` as an alternative serializer.
## Defining API Interfaces
Create interfaces with HTTP method attributes that map to API endpoints.
```csharp
using Refit;
namespace MyApp.ApiClients;
public interface IProductsApi
{
[Get("/api/products")]
Task<List<ProductDto>> GetAllAsync(
[Query] int page = 1,
[Query] int pageSize = 20,
[Query] string? category = null);
[Get("/api/products/{id}")]
Task<ProductDto> GetByIdAsync(int id);
[Post("/api/products")]
Task<ProductDto> CreateAsync([Body] CreateProductRequest request);
[Put("/api/products/{id}")]
Task<ProductDto> UpdateAsync(int id, [Body] UpdateProductRequest request);
[Delete("/api/products/{id}")]
Task DeleteAsync(int id);
[Get("/api/products/search")]
Task<List<ProductDto>> SearchAsync([Query] ProductSearchQuery query);
[Multipart]
[Post("/api/products/{id}/image")]
Task UploadImageAsync(int id, [AliasAs("file")] StreamPart image);
}
public record ProductDto(int Id, string Name, decimal Price, string Category);
public record CreateProductRequest(string Name, decimal Price, string Category);
public record UpdateProductRequest(string? Name, decimal? Price, string? Category);
public record ProductSearchQuery(string? Term, decimal? MinPrice, decimal? MaxPrice);
```
## ASP.NET Core Registration with HttpClientFactory
Register Refit clients with the DI container using `AddRefitClient`.
```csharp
using Refit;
using MyApp.ApiClients;
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddRefitClient<IProductsApi>()
.ConfigureHttpClient(client =>
{
client.BaseAddress = new Uri("https://api.products.com");
client.DefaultRequestHeaders.Add("Accept", "application/json");
client.Timeout = TimeSpan.FromSeconds(30);
})
.AddStandardResilienceHandler();
builder.Services
.AddRefitClient<IOrdersApi>(new RefitSettings
{
ContentSerializer = new SystemTextJsonContentSerializer(
new System.Text.Json.JsonSerializerOptions
{
PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull
})
})
.ConfigureHttpClient(client =>
{
client.BaseAddress = new Uri("https://api.orders.com");
})
.AddHttpMessageHandler<AuthHeaderHandler>();
var app = builder.Build();
app.MapGet("/products", async (IProductsApi api, int page = 1) =>
Results.Ok(await api.GetAllAsync(page)));
app.Run();
```
## Authentication with Delegating Handlers
Add authentication tokens to requests using `DelegatingHandler`.
```csharp
using System.Net.Http.Headers;
namespace MyApp.Http;
public class AuthHeaderHandler : DelegatingHandler
{
private readonly ITokenService _tokenService;
public AuthHeaderHandler(ITokenService tokenService)
{
_tokenService = tokenService;
}
protected override async Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request,
CancellationToken cancellationToken)
{
var token = await _tokenService.GetAccessTokenAsync(cancellationToken);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
return await base.SendAsync(request, cancellationToken);
}
}
// Registration
builder.Services.AddTransient<AuthHeaderHandler>();
builder.Services.AddScoped<ITokenService, TokenService>();
builder.Services
.AddRefitClient<IProductsApi>()
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.products.com"))
.AddHttpMessageHandler<AuthHeaderHandler>();
```
## Error Handling with ApiException
Handle API errors using Refit's `ApiException` and `ApiResponse<T>`.
```csharp
using Refit;
namespace MyApp.ApiClients;
// Option 1: Use ApiResponse<T> for non-throwing error handling
public interface IOrdersApi
{
[Get("/api/orders/{id}")]
Task<ApiResponse<OrderDto>> GetByIdAsync(int id);
[Post("/api/orders")]
Task<ApiResponse<OrderDto>> CreateAsync([Body] CreateOrderRequest request);
}
// Service using ApiResponse<T>
public class OrderService
{
private readonly IOrdersApi _api;
private readonly ILogger<OrderService> _logger;
public OrderService(IOrdersApi api, ILogger<OrderService> logger)
{
_api = api;
_logger = logger;
}
public async Task<OrderResult> GetOrderAsync(int id)
{
using var response = await _api.GetByIdAsync(id);
if (response.IsSuccessStatusCode && response.Content is not null)
{
return OrderResult.Success(response.Content);
}
_logger.LogWarning(
"Failed to get order {Id}. Status: {Status}, Error: {Error}",
id,
response.StatusCode,
response.Error?.Content);
return response.StatusCode switch
{
System.Net.HttpStatusCode.NotFound => OrderResult.NotFound(),
System.Net.HttpStatusCode.Unauthorized => OrderResult.Unauthorized(),
_ => OrderResult.Error($"API returned {response.StatusCode}")
};
}
}
// Option 2: Use try-catch with ApiException
public class ProductService
{
private readonly IProductsApi _api;
public ProductService(IProductsApi api) => _api = api;
public async Task<ProductDto?> GetProductAsync(int id)
{
try
{
return await _api.GetByIdAsync(id);
}
catch (ApiException ex) when (ex.StatusCode == System.Net.HttpStatusCode.NotFound)
{
return null;
}
catch (ApiException ex)
{
var errorBody = await ex.GetContentAsAsync<ProblemDetails>();
throw new ExternalApiException(
$"Products API error: {errorBody?.Detail ?? ex.Message}",
ex);
}
}
}
```
## Headers and Dynamic Configuration
Use static and dynamic headers on interfaces and methods.
```csharp
using Refit;
namespace MyApp.ApiClients;
[Headers("User-Agent: MyApp/1.0", "Accept: application/json")]
public interface IExternalApi
{
[Get("/data")]
[Headers("Cache-Control: no-cache")]
Task<DataResponse> GetFreshDataAsync();
[Get("/data")]
Task<DataResponse> GetCachedDataAsync();
[Post("/data")]
Task<DataResponse> CreateDataAsync(
[Body] DataRequest request,
[Header("X-Idempotency-Key")] string idempotencyKey,
[Header("X-Request-Id")] string requestId);
[Get("/data")]
Task<DataResponse> GetDataWithAuthAsync(
[Authorize("Bearer")] string token);
}
```
## Refit vs Other HTTP Client Libraries
| Feature | Refit | RestSharp | HttpClient | Flurl |
|---|---|---|---|---|
| Approach | Interface + attributes | Builder pattern | Manual requests | Fluent URL builder |
| Code generation | Source generator | None | None | None |
| Type safety | Compile-time | Runtime | Runtime | Runtime |
| Serialization | Auto (STJ / Newtonsoft) | Auto (STJ / Newtonsoft) | Manual | Auto (STJ / Newtonsoft) |
| HttpClientFactory | Built-in integration | v107+ support | Native | Built-in integration |
| Error handling | ApiException / ApiResponse | RestResponse | HttpResponseMessage | FlurlHttpException |
| Multipart upload | `[Multipart]` + `StreamPart` | `AddFile()` | `MultipartFormDataContent` | `PostMultipartAsync()` |
| Query objects | `[Query]` on complex types | `AddQueryParameter()` | Manual string building | `SetQueryParams()` |
## Best Practices
1. **Define one Refit interface per API domain** (e.g., `IProductsApi`, `IOrdersApi`, `IUsersApi`) rather than one monolithic interface, so that each interface can be registered with different `HttpClient` configurations (base URL, timeout, retry policy) and injected only where needed.
2. **Use `AddRefitClient<T>()` with `ConfigureHttpClient()` instead of `RestService.For<T>()`** so that Refit clients participate in `HttpClientFactory`'s handler lifecycle management, preventing socket exhaustion from creating `HttpClient` instances manually.
3. **Return `Task<ApiResponse<T>>` instead of `Task<T>` on interface methods** when the calling code needs to inspect HTTP status codes, headers, or error bodies without catching exceptions, because `ApiResponse<T>` wraps the response metadata and deserialized content together.
4. **Add resilience with `.AddStandardResilienceHandler()` from `Microsoft.Extensions.Http.Resilience`** on `AddRefitClient` registrations to automatically retry transient failures, apply circuit breakers, and enforce timeouts, rather than implementing retry logic in the consuming service.
5. **Use `[Query]` on complex type parameters** to automatically flatten object properties into query string parameters (`?term=shoes&minPrice=10&maxPrice=100`) instead of building query strings manually, keeping method signatures clean and type-safe.
6. **Implement `DelegatingHandler` for cross-cutting concerns** (authentication, logging, correlation IDs) and register them with `.AddHttpMessageHandler<T>()`, so that all requests through a Refit client include the required headers without modifying each interface method.
7. **Use `[Authorize("Bearer")]` on a string parameter for per-request token injection** in scenarios where different calls may use different tokens (multi-tenant, user impersonation), instead of a shared `DelegatingHandler` that always attaches the same token.
8. **Configure `RefitSettings` with `SystemTextJsonContentSerializer`** and explicit `JsonSerializerOptions` (camelCase naming, null handling) to ensure serialization matches the API contract, rather than relying on default serializer settings that may differ between .NET versions.
9. **Dispose `ApiResponse<T>` objects** by wrapping them in `using` statements or calling `Dispose()` after reading the content, because `ApiResponse<T>` holds an `HttpResponseMessage` whose `Content` stream should be released after use to free network connections.
10. **Use `[AliasAs("name")]` on parameters and properties** when the C# property name differs from the API's expected parameter name (e.g., `[AliasAs("page_size")] int pageSize`), because Refit uses the C# name by default and API servers with snake_case conventions will reject unrecognized parameter names.
Files in this package (21)
- AGENTS.md 11 KB
- README.md 1 KB
- SKILL.md 12 KB
- metadata.json 1 KB
- rules/_sections.md 2 KB
- rules/_template.md 1 KB
- rules/refit-add-resilience-with-addstandardresiliencehandler-from.md 1 KB
- rules/refit-configure-httpclient-with-policies.md 1 KB
- rules/refit-configure-refitsettings-with-systemtextjsoncontentserializer.md 1 KB
- rules/refit-define-clear-interfaces.md 1 KB
- rules/refit-define-one-refit-interface-per-api-domain.md 1 KB
- rules/refit-dispose-apiresponse-t-objects.md 1 KB
- rules/refit-handle-errors-with-try-catch.md 1 KB
- rules/refit-implement-delegatinghandler-for-cross-cutting-concerns.md 1 KB
- rules/refit-return-task-apiresponse-t-instead-of-task-t-on-interface.md 1 KB
- rules/refit-use-addrefitclient-t-with-configurehttpclient-instead-of.md 1 KB
- rules/refit-use-aliasas-name-on-parameters-and-properties.md 1 KB
- rules/refit-use-authorize-bearer-on-a-string-parameter-for-per-request.md 1 KB
- rules/refit-use-dependency-injection.md 1 KB
- rules/refit-use-proper-http-verbs.md 1 KB
- rules/refit-use-query-on-complex-type-parameters.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Tyler-R-Kendrick/agent-skills | 100 | MIT |
| spacedock-dev/spacedock | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 81b63fc2d10a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100restsharp
USE FOR: Making HTTP API calls using RestSharp's fluent request builder with automatic serialization, authenticators, and response handling. Use when consuming REST APIs that need configurable serialization, file uploads, and built-in authentication support without defining… - 100httpclient-factory
IHttpClientFactory and typed HTTP clients for .NET 10 applications. Covers named/typed/keyed clients, DelegatingHandlers, resilience with Microsoft.Extensions.Http.Resilience, and testing patterns. Load this skill when configuring HTTP clients, adding retry/circuit breaker… - 100angular-http-client
Integrate HttpClient, Interceptors, and API interactions in Angular. Use when integrating HttpClient, writing interceptors, or handling API calls in Angular. - 80Angular HttpClient Migration v6
Migrate from Angular HttpModule and Http to HttpClientModule and HttpClient during the Angular 5 to 6 era. Use when legacy HTTP APIs block modern Angular usage. - 100api-client-generator
Generate api client generator operations. Auto-activating skill for API Integration. Triggers on: api client generator, api client generator Part of the API Integration skill category. Use when working with APIs or building integrations. Trigger with phrases like "api client… - 100api-integration
Use when consuming external APIs, integrating third-party services, generating type-safe API clients, implementing authentication flows, or working with OpenAPI/Swagger, GraphQL, or REST specs. TypeScript-primary with language-agnostic patterns.