Shaunebu.Common.RESTClient 1.0.1

🧠 Shaunebu.RESTClient

🌐 Overview

Shaunebu.RESTClient is a next-generation, attribute-driven REST client framework for .NET — inspired by the simplicity of Refit, but engineered from the ground up to solve the challenges of real-world enterprise environments. While Refit focuses on mapping C# interfaces to REST endpoints, RESTClient goes beyond that philosophy:

👉 it provides a full SDK-generation platform, ready for production, observability, resilience, and extensibility.

Modern distributed systems require more than just making HTTP calls. They demand:

• automatic retries, timeouts, and circuit breakers

• telemetry for tracing and performance monitoring

• multi-format serialization (JSON, XML, MessagePack, Protobuf)

• typed fallbacks for offline or degraded operation

• caching, logging, and security layers

• pluggable interceptors

• seamless DI integration

• progress reporting for long-running uploads/downloads

RESTClient delivers all of this out-of-the-box, with zero extra setup. It is fully declarative, fully extensible, and completely aligned with how .NET developers already work.

🔧 How It Works

RESTClient dynamically generates a strongly typed REST client at runtime based on an interface decorated with attributes.
Internally, the pipeline looks like this:

Interface  
   → Attribute Parser  
      → Proxy Builder  
         → Interceptor Pipeline  
            → Serialization & Content Negotiation  
               → Resilience Engine (Polly)  
                  → HttpClient Transport  
                     → Response Deserialization  

Each part of this pipeline is extensible, customizable, and replaceable. This architecture allows RESTClient to provide:

• per-method resilience

• automatic serialization based on headers

• observability hooks

• request/response interceptors

• fallback logic

• caching

• runtime validation

• total control over HTTP behavior

with no boilerplate.

🎯 Design Principles

RESTClient is built on a clear philosophy:

1. Declarative by Default

Developers define behavior through attributes — not configuration files or boilerplate.

2. Production-Ready Out-of-the-Box

Retries, timeouts, logging, diagnostics, and telemetry are enabled automatically.

3. Extensible Everywhere

Interceptors, serializers, URL formatters, fallback providers — all pluggable.

4. Observable by Design

Built-in OpenTelemetry tracing, metrics, and structured logging support.

5. Safe Failure Behavior

Typed fallbacks and caching allow clients to operate gracefully under failure.

6. Multi-Format Native Support

JSON, XML, MessagePack, Protobuf, FormUrlEncoded, Multipart.

7. Zero Boilerplate

A single AddRESTClient<T>() registers everything needed.

🚀 Why Shaunebu.RESTClient?

Refit provides a great abstraction for defining REST APIs as interfaces.
Shaunebu.RESTClient takes this philosophy and extends it into a complete, production-ready SDK framework.

• 🔧 Plug-and-play registration — just one line of DI setup.
• 🧱 Enterprise resilience stack — retries, circuit breakers, timeouts, fallback providers.
• 📦 Multi-format serialization — JSON, XML, MessagePack, Protobuf, UrlEncoded.
• 🧩 Interceptor pipeline — security, logging, caching, metrics, OpenTelemetry.
• 🌐 Dynamic content negotiation based on Accept headers.
• 💥 Fallback providers that return typed responses without throwing exceptions.
• ⏱️ Real upload/download progress tracking.
• ⚙️ Extensible architecture (custom interceptors, serializers, negotiators).

📦 Installation

dotnet add package Shaunebu.Common.RESTClient

🧭 Quick Start

public interface IPostsApi
{
    [Get("/posts")]
    Task<List<Post>> GetPostsAsync();

    [Post("/posts")]
    Task<Post> CreatePostAsync([Body] CreatePostRequest request);
}

// Dependency Injection
services.AddRESTClient<IPostsApi>("https://jsonplaceholder.typicode.com");

// Usage
var api = provider.GetRequiredService<IPostsApi>();
var result = await api.CreatePostAsync(new CreatePostRequest
{
    Title = "Hello World",
    Body = "RESTClient is amazing!"
});

✅ No configuration needed — serializers, resilience policies, interceptors, and handlers are automatically registered.

⚙️ Centralized Configuration

All global settings are managed through RESTClientOptions:

services.AddRESTClient(options =>
{
    options.Timeout.RequestTimeoutSeconds = 30;
    options.Resilience.RetryCount = 3;
    options.Resilience.CircuitBreakerThreshold = 5;
    options.DefaultCollectionFormat = CollectionFormat.Csv;
    options.BufferResponse = true;
});

Example of appsettings.json registration

{
  "RestClients": [
    {
      "Interface": "MyApp.Api.IPostsApi, MyApp",
      "BaseUrl": "https://jsonplaceholder.typicode.com"
    }
  ]
}

Then:

services.AddRESTClientsFromConfig(Configuration);

🧩 Attribute Reference

📜 Multi-Serialization and Content Negotiation

Shaunebu.RESTClient can serialize and deserialize payloads dynamically based on the Accept or Content-Type headers.

[Post("/users")]
Task<User> AddUser([Body(Method = BodySerializationMethod.Json)] User user);

[Post("/files/upload")]
[Multipart(Boundary = "----CustomBoundary")]
Task<ApiResponse<string>> UploadFile([AliasAs("file")] StreamPart file);

Supported Serializers

You can register your own serializers:

services.TryAddSingleton<IContentSerializer, MyCustomSerializer>();

🧠 Dynamic Content Negotiation

The ContentNegotiator automatically chooses the correct serializer based on the request’s Accept header. Example:

[Get("/data")]
[Headers("Accept: application/x-protobuf")]
Task<MyResponse> GetDataInProtobuf();

The library will automatically:

• use ProtobufSerializer to serialize/deserialize the body,

• and send the correct Content-Type.

💪 Declarative Resilience (Polly Built-In)

Built-in attribute-level resilience, powered by Polly:

[Get("/data")]
[Retry(3, 2)] // Retries with exponential backoff
[Timeout(5)] // Timeout after 5 seconds
[CircuitBreaker(3, 10)] // Breaks circuit after 3 errors for 10s
Task<DataResponse> GetDataAsync();

No need to register Polly handlers manually — everything is wired automatically through DI.

💥 Typed Fallback Providers

If a request fails, the fallback provider can return a typed result instead of throwing an exception.

[Get("/users/{id}")]
[Fallback(typeof(UserFallbackProvider))]
Task<User> GetUserAsync(int id);

public class UserFallbackProvider
{
    public Task<User> GetFallbackAsync(Exception ex) =>
        Task.FromResult(new User { Id = -1, Name = "Offline User" });
}

When triggered, the response includes a header:

X-Fallback-Executed: true

⏱️ Progress Tracking

Real-time upload and download progress tracking using IProgress<double>:

[Post("/upload")]
Task<ApiResponse> UploadLargeFileAsync([Body] StreamPart file, IProgress<double> progress);

The progress value reports 0.0 → 1.0 (0% → 100%).

🔄 Interceptors and Middleware

Interceptors allow you to hook into the entire request/response lifecycle.

public class MyLoggingInterceptor : IRESTInterceptor
{
    public Task OnRequestAsync(RequestContext ctx)
    {
        Console.WriteLine($"➡️ {ctx.Request.Method} {ctx.Request.RequestUri}");
        return Task.CompletedTask;
    }

    public Task OnResponseAsync(ResponseContext ctx)
    {
        Console.WriteLine($"⬅️ {ctx.Response.StatusCode}");
        return Task.CompletedTask;
    }
}

Add via DI:

services.TryAddSingleton<IRESTInterceptor, MyLoggingInterceptor>();

Built-in Interceptors

• 🔐 SecurityInterceptor

• 🧱 ResilienceInterceptor

• 🪣 CachingInterceptor

• 🧭 OpenTelemetryInterceptor

• 🪵 LoggingInterceptor

• 🧪 DebugInterceptor

• 💥 FallbackInterceptor

• ⚙️ PollyDebugInterceptor

• 📊 MetricsInterceptor

🧱 Caching and Metrics

Out of the box support for:

• ICacheStore (default: MemoryCacheStore)

• CachingInterceptor (automatic response caching)

• OpenTelemetry tracing (OpenTelemetryInterceptor)

• Metrics gathering (MetricsInterceptor)

📊 Full Feature Comparison

🧠 Deep Comparison with Refit

While Refit is excellent for lightweight API calls, it has limitations in enterprise scenarios:

Refit is ideal for:

• Simple REST wrappers

• Mobile apps

• Low-infrastructure projects

• Rapid prototypes

RESTClient is designed for:

• Microservices

• Enterprise APIs

• SDK development

• Mission-critical integrations

• Highly observable systems

• Environments where resiliency is mandatory

In short:
Refit helps you call APIs — RESTClient helps you build SDKs for APIs.

🧩 Extending Shaunebu.RESTClient

Custom Serializer

Implement IContentSerializer to plug in any serialization logic.

Custom Interceptor

Add your own interceptor for metrics, logging, or security checks.

Custom Fallback Provider

Attach to [Fallback(typeof(...))] for custom recovery logic.

Custom Url Parameter Formatter

Implement IUrlParameterFormatter to change query escaping globally.

🧩 Example: Complex Client Definition

[Headers("Authorization: Bearer")]
[Host("https://api.override.com")]
public interface IComplexApi
{
    [Get("/users/{id}")]
    [Fallback(typeof(UserFallback))]
    [Retry(3, 1)]
    [Timeout(10)]
    Task<User> GetUserAsync(int id);

    [Post("/upload")]
    [Multipart(Boundary = "----ShaunebuBoundary")]
    Task<ApiResponse> UploadFileAsync([AliasAs("file")] StreamPart file, IProgress<double> progress);
}

🧰 Recommended Use Cases

• 🧱 SDK Generation for enterprise APIs

• ☁️ Microservice Clients with per-method resiliency

• 🧩 Highly observable integrations (with OpenTelemetry)

• 📊 Data ingestion services requiring metrics and caching

• 💾 Offline-capable APIs using fallbacks and memory cache

🧩 Credits

Originally inspired by Refit, but re-engineered by Jorge Perales Díaz
for real-world, large-scale systems that need reliability, observability, and full-stack resilience.

🗺️ ** Roadmap **

📄 License

MIT © Shaunebu 2025