Skip to content
Skills Library
Programming · Building & coding

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).

Licence
MIT
Last repository change
09.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
21
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 09.06.2026, without references to retired models or APIs.

Licence

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

  1. Overview
  2. Defining API Interfaces
  3. ASP.NET Core Registration with HttpClientFactory
  4. Authentication with Delegating Handlers
  5. Error Handling with ApiException
  6. Headers and Dynamic Configuration
  7. Refit vs Other HTTP Client Libraries
  8. Best Practices
Original SKILL.md headings · 281 lines, 1,086 words
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

RepositoryScoreLicence
This page · Tyler-R-Kendrick/agent-skills100MIT
spacedock-dev/spacedock100Apache-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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.