Convert C# interfaces into type-safe REST clients using Refit, simplifying API calls and dependency injection in .NET.
Install
mkdir -p .claude/skills/refit && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/14276" && unzip -o skill.zip -d .claude/skills/refit && rm skill.zipInstalls to .claude/skills/refit
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use Refit to define type-safe REST clients in .NET as C# interfaces backed by HttpClient — covering interface definition (HTTP verb attributes, parameter binding, return types), DI registration with AddRefitClient, DelegatingHandler pipelines for auth/headers/logging, error handling with IApiResponse, RefitSettings, and multipart uploads. Trigger whenever the user writes, reviews, or asks about Refit clients, REST API interfaces, AddRefitClient, IApiResponse, ApiException, DelegatingHandler for HTTP, typed HTTP clients, RestService.For, or consuming HTTP APIs in .NET — even if they don't mention "Refit" by name. Always prefer this skill over guessing; Refit's attribute model, IApiResponse vs throws-by-default behavior, handler chain ordering, and scoped-client lifetime rules all have non-obvious failure modes that are easy to get wrong.Key capabilities
- →Define type-safe REST clients using C# interfaces
- →Generate HTTP requests from interface definitions
- →Register Refit clients with dependency injection
- →Implement DelegatingHandler pipelines for authentication and logging
- →Handle API errors using `IApiResponse` or `ApiException`
How it works
Refit turns a C# interface annotated with HTTP verb attributes into a working client backed by `HttpClient`. It generates the implementation at compile time or runtime and integrates with DI.
Inputs & outputs
When to use refit
- →Define REST API contracts
- →Simplify HttpClient logic
- →Handle authentication via DelegatingHandlers
- →Map API errors to interfaces
About this skill
Refit
Refit turns a C# interface you annotate with HTTP verb attributes into a working client backed by HttpClient. You write the contract; Refit generates the implementation at compile time (source generator) or runtime.
NuGet packages
Refit— core (always required)Refit.HttpClientFactory—AddRefitClient<T>()DI integration (add for ASP.NET Core / DI apps)
Quick reference
| Topic | See |
|---|---|
| HTTP verbs, parameter binding, return types, headers | interface-design.md |
DI registration, AddRefitClient, RefitSettings, scoped clients | di-registration.md |
| Auth handlers, Bearer tokens, per-request and static headers | authentication.md |
IApiResponse, ApiException, non-throwing error handling | error-handling.md |
The golden path
// 1. Define the interface
public interface IProductsClient
{
[Get("/api/products/{id}")]
Task<ProductDto> GetProductAsync(Guid id, CancellationToken cancellationToken = default);
[Post("/api/products")]
Task<IApiResponse<ProductDto>> CreateProductAsync([Body] CreateProductRequest body, CancellationToken cancellationToken = default);
}
// 2. Register with DI
services.AddRefitClient<IProductsClient>()
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"))
.AddHttpMessageHandler<AuthHandler>()
.AddStandardResilienceHandler();
// 3. Use via injection
public class ProductsPage(IProductsClient client)
{
async Task LoadAsync()
{
var product = await client.GetProductAsync(id);
}
}
Critical rules
- Always include
CancellationToken cancellationToken = defaultas the last parameter on every method. - Handler chain order matters: the first
AddHttpMessageHandlercall is outermost (executes first on send, last on receive). Typical order: Resilience → Auth → Correlation → Network. - Never register scoped DelegatingHandlers as singletons — they'll capture scoped services and cause stale state. Register handlers as
AddTransient. IApiResponse<T>suppresses throwing on non-2xx; rawTask<T>throwsApiException. Choose at the interface level per method.InnerHandlermust benullwhen registering handlers via DI (AddHttpMessageHandler); assign it only when constructing manually withRestService.For<T>.
When not to use it
- →When manually constructing `HttpClient` requests is preferred
- →When a different HTTP client library is already in use
Prerequisites
Limitations
- →It requires `CancellationToken cancellationToken = default` on every method.
- →Handler chain order matters for `DelegatingHandlers`.
How it compares
This skill uses Refit to automatically generate HTTP client implementations from C# interfaces, simplifying API consumption and ensuring type safety compared to manual `HttpClient` usage.
Compared to similar skills
refit side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| refit (this skill) | 0 | 4mo | No flags | Intermediate |
| microsoft-code-reference | 7 | 5mo | Review | Beginner |
| dotnet-backend-patterns | 7 | 5mo | No flags | Advanced |
| azure-maps-search-dotnet | 2 | 3mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by aalmada
View all by aalmada →You might also like
microsoft-code-reference
github
Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs.
dotnet-backend-patterns
wshobson
Master C#/.NET backend development patterns for building robust APIs, MCP servers, and enterprise applications. Covers async/await, dependency injection, Entity Framework Core, Dapper, configuration, caching, and testing with xUnit. Use when developing .NET backends, reviewing C# code, or designing API architectures.
azure-maps-search-dotnet
microsoft
Azure Maps SDK for .NET. Location-based services including geocoding, routing, rendering, geolocation, and weather. Use for address search, directions, map tiles, IP geolocation, and weather data. Triggers: "Azure Maps", "MapsSearchClient", "MapsRoutingClient", "MapsRenderingClient", "geocoding .NET", "route directions", "map tiles", "geolocation".
azure-servicebus-dotnet
microsoft
Azure Service Bus SDK for .NET. Enterprise messaging with queues, topics, subscriptions, and sessions. Use for reliable message delivery, pub/sub patterns, dead letter handling, and background processing. Triggers: "Service Bus", "ServiceBusClient", "ServiceBusSender", "ServiceBusReceiver", "ServiceBusProcessor", "message queue", "pub/sub .NET", "dead letter queue".
m365-agents-dotnet
microsoft
Microsoft 365 Agents SDK for .NET. Build multichannel agents for Teams/M365/Copilot Studio with ASP.NET Core hosting, AgentApplication routing, and MSAL-based auth. Triggers: "Microsoft 365 Agents SDK", "Microsoft.Agents", "AddAgentApplicationOptions", "AgentApplication", "AddAgentAspNetAuthentication", "Copilot Studio client", "IAgentHttpAdapter".
azure-ai-openai-dotnet
microsoft
Azure OpenAI SDK for .NET. Client library for Azure OpenAI and OpenAI services. Use for chat completions, embeddings, image generation, audio transcription, and assistants. Triggers: "Azure OpenAI", "AzureOpenAIClient", "ChatClient", "chat completions .NET", "GPT-4", "embeddings", "DALL-E", "Whisper", "OpenAI .NET".