Shaunebu.Common.RESTClient The Next-Generation REST Framework for .NET
🚀 Introducing Shaunebu.Common.RESTClient — The Next-Generation REST Framework for .NET
Modern .NET applications demand far more than simple HTTP calls. We now build microservices, distributed systems, mobile apps, SDKs, and enterprise integrations where reliability, observability, and resiliency aren't optional — they are essential.
Tools like Refit brought simplicity and elegance to REST interfaces. But once we enter real-world scenarios — retries, fallbacks, caching, multi-serialization, OpenTelemetry, token refresh, offline modes, resilience policies — things quickly get complicated. Today, I’m excited to introduce:
🎉 Shaunebu.Common.RESTClient
A next-generation, attribute-driven REST framework for .NET
built for enterprise resiliency, observability, extensibility, and simplicity. This is not “just another Refit clone.”
This is the evolution.
🌐 Overview
Shaunebu.Common.RESTClient lets you define REST APIs using interfaces — just like Refit — but adds an entire production-grade stack:
- ✔️ Automatic Polly-based resiliency
- ✔️ Typed fallbacks
- ✔️ Dynamic multi-serialization (JSON, XML, Protobuf, MessagePack)
- ✔️ Interceptor pipeline for logging, telemetry, caching & more
- ✔️ OpenTelemetry auto-instrumentation
- ✔️ Unified DI registration
- ✔️ Upload & download progress tracking
- ✔️ Offline support through fallback providers
- ✔️ Content negotiation based on Accept headers
- ✔️ Fully extensible architecture
Everything works without extra setup.
🧠 Why I built this library
Refit is amazing — I've used it for years.
But in real-world applications I kept facing issues like:
- “How do I retry only this method?”
- “How do I apply a circuit breaker per call?”
- “How do I use multiple serializers?”
- “How do I log every request and response?”
- “How do I send protobuf on one endpoint and JSON on another?”
- “How do I add fallback logic?”
- “How do I track upload/download progress?”
- “How do I make everything observable with OpenTelemetry?”
I wanted a framework that feels as simple as Refit,
but powered for enterprise, built around modern system demands. So I built:
🔥 A production-ready REST SDK generator
RESTClient is designed with the philosophy:
“Refit lets you call APIs — RESTClient lets you build SDKs for APIs.”
🔧 How It Works (Architecture)
RESTClient has a clean, layered architecture:
Interface
↓
Attribute Parser
↓
Proxy Generator
↓
Interceptor Pipeline
↓
Serializer Selection (Content Negotiation)
↓
Resilience Engine (Polly)
↓
HttpClient Transport
↓
Response Materializer
Each stage is extensible, replaceable, and designed for high-performance.
✨ Quick Start
Define your API interface:
Register it:
Use it:
Zero boilerplate. Everything is ready instantly.
🛡️ Enterprise-Grade Resilience (Polly Built-In)
Add retries, timeouts, circuit breakers, or bulkhead isolation — per method.
No need to manually configure HttpClient handlers. RESTClient does it automatically. ✔️
💥 Typed Fallback Providers (Offline Mode)
Gracefully handle failure without throwing exceptions:
Provider:
RESTClient automatically adds:
Perfect for:
- Offline apps
- Partial outages
- Fail-soft architectures
📦 Multi-Serialization (JSON, XML, Protobuf, MessagePack)
Per-method control:
Or automatic based on Accept header:
RESTClient picks the right serializer.
No configuration. No custom HttpContent.
Just works. ✔️
🔍 Interceptor Pipeline
RESTClient includes a full middleware-like pipeline: Built-in interceptors:
- 🔐 SecurityInterceptor
- 🧱 ResilienceInterceptor
- 🪵 LoggingInterceptor
- 🧭 OpenTelemetryInterceptor
- 🧪 DebugInterceptor
- 🪣 CachingInterceptor
- 💥 FallbackInterceptor
- 📊 MetricsInterceptor
Add your own:
Register it:
📊 Observability Built-In (OpenTelemetry)
RESTClient emits:
- trace spans
- request attributes
- latency metrics
- error signals
- fallback flags
- retry counts
Automatically. You get distributed tracing across microservices with zero setup.
⏱️ Upload / Download Progress
Progress reports 0.0 → 1.0. Perfect for mobile, desktop, and MAUI apps.
🧩 Advanced Attribute Model
RESTClient supports over 20 attributes to fine-tune behavior:
[Get]/[Post]/[Put]/[Delete]/[Patch][Headers]/[Header][AliasAs][Fallback][Retry]/[Timeout]/[CircuitBreaker]/[Bulkhead][Multipart][Query][Host][RateLimit][HealthCheck]
Extremely flexible.
🧱 Caching & Metrics Support
Via interceptors:
- memory cache
- distributed cache
- method-level control
- cache invalidation
- cache keys based on URL, query, headers
Plus full metrics via OpenTelemetry.
🆚 Comparison: RESTClient vs Refit
| Feature | RESTClient | Refit |
|---|---|---|
| DI Unified Registration | ✅ | ❌ |
| Centralized Config | ✅ | ⚠️ |
| Polly Integration | Automatically | Manual |
| Resilience Attributes | ✅ | ❌ |
| Typed Fallbacks | ✅ | ❌ |
| Multi-Serialization | JSON, XML, Protobuf, MsgPack | JSON only |
| Content Negotiation | Automatic | ❌ |
| Interceptor Pipeline | Full | ❌ |
| Logging + Telemetry | Built-in | Partial |
| Caching | Yes | ❌ |
| Upload Progress | Yes | ❌ |
| Host Override | Yes | Yes |
| OpenTelemetry | Integrated | ❌ |
| Production Ready | ✔✔✔ | ✔ |
🛠️ Use Cases
1. SDK Development
Build full API SDKs with minimal code.
2. Microservices
Per-method resilience, tracing, and caching.
3. Mobile Apps / MAUI
Offline fallbacks + progress tracking.
4. External Integrations
Multiple serializers per endpoint.
5. High Observability Systems
Every request is traceable.
🎉 Final Thoughts
Shaunebu.Common.RESTClient is built to bring together the simplicity of Refit with the power of enterprise frameworks such as:
- Polly
- AspNetCore middleware
- OpenTelemetry
- MessagePack / Protobuf
- Distributed caching
If you’re building anything modern with .NET — RESTClient will make your integrations faster, safer, more observable, and easier to maintain.