FluentHttpBuilder 1.0.4

FluentHttpBuilder

A fluent, type-safe HTTP request builder for .NET 🚀

✨ Features

• 🎯 Fluent API - Easy to read and write
• 🔒 Type-Safe - Compiler protects you from mistakes
• 🌐 All HTTP Methods - GET, POST, PUT, DELETE, PATCH
• 📦 JSON Support - Automatic serialization/deserialization
• 🔑 Authentication - Bearer tokens and custom headers
• ⚙️ Configurable - Timeout, headers, and more
• ❌ Error Handling - Graceful error responses
• 🛡️ Circuit Breaker - Built-in resiliency, zero dependencies

📦 Installation

dotnet add package FluentHttpBuilder

Or via Package Manager:

Install-Package FluentHttpBuilder

🚀 Quick Start

Simple GET Request

using FluentHttpBuilder;

var response = await HttpRequestBuilder.Create()
    .WithUrl("https://jsonplaceholder.typicode.com/posts/1")
    .Get()
    .SendAsync();

Console.WriteLine($"Status: {response.StatusCode}");
Console.WriteLine($"Content: {response.Content}");

POST Request with JSON

var newPost = new { 
    title = "My Post", 
    body = "This is the content", 
    userId = 1 
};

var response = await HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/posts")
    .Post()
    .WithJsonBody(newPost)
    .SendAsync();

if (response.IsSuccess)
{
    Console.WriteLine("Post created successfully!");
}

Authenticated Request

var response = await HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/users")
    .Get()
    .WithBearerToken("your-access-token")
    .SendAsync();

Custom Headers & Timeout

var response = await HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/data")
    .Get()
    .AddHeader("X-Custom-Header", "value")
    .AddHeader("X-API-Version", "2.0")
    .WithTimeout(60) // 60 seconds
    .SendAsync();

🛡️ Circuit Breaker

Protect your app from cascading failures caused by unreliable downstream services. The circuit breaker detects repeated failures and short-circuits calls before they hit the network, giving the failing service time to recover.

States

Usage

using FluentHttpBuilder.Resilience;

var request = HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/data")
    .Get()
    .WithTimeout(10)
    .WithCircuitBreaker(options =>
    {
        // Trip the breaker after 3 consecutive failures
        options.FailureThreshold = 3;

        // Keep the circuit open for 60 seconds before retrying
        options.OpenDuration = TimeSpan.FromSeconds(60);

        // Log every state transition
        options.OnStateChanged = (from, to) =>
            Console.WriteLine($"[CircuitBreaker] {from} → {to}");
    });

try
{
    var response = await request.SendAsync();

    if (response.IsSuccess)
        Console.WriteLine(response.Content);
}
catch (CircuitBreakerOpenException ex)
{
    // Circuit is open — fail fast, no network call was made
    Console.WriteLine($"Service unavailable: {ex.Message}");
    Console.WriteLine($"Current State: {ex.State}");

    // Implement fallback logic here (e.g. return cached data)
}

Configuration Options

How it works

         failures >= threshold
Closed ──────────────────────► Open
  ▲                               │
  │    probe succeeds             │ openDuration elapsed
  └──────────────── HalfOpen ◄───┘
                       │
                       │ probe fails
                       └──────────► Open

Zero dependencies — the circuit breaker is built from scratch using pure .NET. No Polly or any third-party packages required.

📚 API Reference

HTTP Methods

Configuration Methods

🎯 Advanced Examples

PUT Request

var updateData = new { 
    title = "Updated Title",
    completed = true 
};

var response = await HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/posts/1")
    .Put()
    .WithJsonBody(updateData)
    .WithBearerToken("token")
    .SendAsync();

DELETE Request

var response = await HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/posts/1")
    .Delete()
    .WithBearerToken("token")
    .SendAsync();

Console.WriteLine(response.IsSuccess ? "Deleted!" : "Failed");

Build Without Executing (for testing)

var request = HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/data")
    .Post()
    .WithJsonBody(new { test = "data" })
    .Build();

Console.WriteLine($"Will send {request.Method} to {request.Url}");
Console.WriteLine($"Body: {request.Body}");

🔧 Response Object

public class FluentHttpResponse
{
    public int StatusCode { get; init; }                      // HTTP status code (200, 404, etc.)
    public string Content { get; init; }                      // Response body as string
    public bool IsSuccess { get; init; }                      // True if 2xx status
    public Dictionary<string, string> Headers { get; init; }  // Response headers
}

💡 Best Practices

1. Reuse HttpClient - The builder uses a static HttpClient internally
2. Handle Errors - Always check response.IsSuccess
3. Set Timeouts - For slow APIs, increase timeout
4. Use Async/Await - All methods are async
5. Use Circuit Breaker - For any external API calls in production

⚠️ Error Handling

var response = await HttpRequestBuilder.Create()
    .WithUrl("https://api.example.com/data")
    .Get()
    .SendAsync();

if (!response.IsSuccess)
{
    Console.WriteLine($"Error: {response.StatusCode}");
    Console.WriteLine($"Message: {response.Content}");
}

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests

📄 License

MIT License - feel free to use in your projects!

🔗 Links

• GitHub Repository
• Report Issues
• NuGet Package

📞 Support

For questions or support, please open an issue on GitHub.

Made with ❤️ for the .NET community