README.md

Reliable.HttpClient Documentation

📖 Complete Documentation Hub - Everything you need to get productive with Reliable.HttpClient

A comprehensive resilience and caching ecosystem for HttpClient with built-in retry policies, circuit breakers, and intelligent response caching.

🚀 Getting Started

New to Reliable.HttpClient? Start here:

1. Getting Started Guide - Step-by-step setup and first implementation
2. Choosing Your Approach - Which features and patterns fit your use case
3. Configuration Reference - Complete options and customization

📚 Documentation Structure

Core Guides

• Getting Started - Installation, basic setup, first examples
• Choosing Your Approach - Decision guide for different scenarios
• Configuration Reference - Complete configuration options
• Advanced Usage - Complex patterns and customization

Specialized Topics

• HTTP Caching Guide - Complete caching documentation and architecture
• Common Business Scenarios - Real-world implementation examples
• HttpClient Substitution - Replacement patterns

Reference Documents

• Configuration Examples - Ready-to-use configuration snippets

🎯 Quick Navigation

I want to...

Goal	Go to
Get started quickly	Getting Started Guide
Choose the right approach	Choosing Guide
Add caching to my API	HTTP Caching Guide
See real-world examples	Common Scenarios
Configure advanced options	Configuration Reference
Replace HttpClient	Substitution Guide

💡 Key Concepts

Core Resilience (Reliable.HttpClient)

Zero-configuration resilience patterns for HttpClient:

• Retry Policies - Exponential backoff with jitter
• Circuit Breaker - Automatic failure detection and recovery
• Timeout Management - Per-request timeout handling

HTTP Caching (Reliable.HttpClient.Caching)

Intelligent response caching with two approaches:

• Universal Caching - Multi-type responses with custom handlers
• Generic Caching - Type-safe caching for specific response types

📖 Complete Architecture: See HTTP Caching Guide for detailed architecture and decision guidance

✨ Universal Response Handlers

Eliminate "Generic Hell" for REST APIs with many entity types:

// Before: Multiple registrations per entity type
services.AddSingleton<IHttpResponseHandler<User>, JsonResponseHandler<User>>();
services.AddSingleton<IHttpResponseHandler<Order>, JsonResponseHandler<Order>>();
// ... many more

// After: One registration for all entity types
services.AddHttpClientWithCache();

public class ApiClient(IHttpClientWithCache client)
{
    public async Task<User> GetUserAsync(int id) =>
        await client.GetAsync<User>($"/users/{id}");

    public async Task<Order> GetOrderAsync(int id) =>
        await client.GetAsync<Order>($"/orders/{id}");
    // Works with any entity type!
}

🔄 HttpClient Substitution Pattern

Seamlessly switch between cached and non-cached implementations:

// Base client using adapter interface
public class ApiClient(IHttpClientAdapter client)
{
    public async Task<T> GetAsync<T>(string endpoint) =>
        await client.GetAsync<T>(endpoint);
}

// Cached version inherits everything, adds caching
public class CachedApiClient : ApiClient
{
    public CachedApiClient(IHttpClientWithCache client) : base(client) { }
    // Automatic caching + cache invalidation methods
}

Package Overview

Package	Purpose	Installation
Reliable.HttpClient	Core resilience (retry + circuit breaker)	dotnet add package Reliable.HttpClient
Reliable.HttpClient.Caching	HTTP response caching extension	dotnet add package Reliable.HttpClient.Caching

Quick Start Example

// Add to your Program.cs
builder.Services.AddHttpClient<ApiClient>(c => c.BaseAddress = new Uri("https://api.example.com"))
    .AddResilience(); // That's it! ✨

// Use anywhere
public class ApiClient(HttpClient client)
{
    public async Task<Data> GetDataAsync() =>
        await client.GetFromJsonAsync<Data>("/endpoint");
}

You now have: Automatic retries + Circuit breaker + Smart error handling

🚀 Need more details? Continue with Getting Started Guide

Why Choose This Ecosystem?

✅ Zero Configuration - Works out of the box with sensible defaults ✅ Complete Solution - Resilience + Caching in one ecosystem ✅ Lightweight - Minimal overhead, maximum reliability ✅ Production Ready - Used by companies in production environments ✅ Easy Integration - One line of code to add resilience, two lines for caching ✅ Secure - SHA256-based cache keys prevent collisions and attacks ✅ Flexible - Use core resilience alone or add caching as needed

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

• 📖 Documentation – This documentation site
• 🐛 Issues – Bug reports and feature requests
• 💬 Discussions – Community discussions

---

Note: This documentation is for the latest version. Check the version badge in the main README for compatibility.