Fluent REST client with circuit breaker, retry policies, certificate support, and object pooling. Provides resilient HTTP communication with configurable error handling and response mapping.
A modern, fluent REST client for .NET with enterprise-grade resilience patterns. Built for developers who value clean code, type safety, and minimal boilerplate.
Why Myth.Rest?
Fluent API: Intuitive, chainable interface that reads like natural language
Enterprise Resilience: Built-in retry policies with exponential backoff and circuit breakers
Type Safety: Strong typing with automatic JSON serialization/deserialization
Zero Configuration: Works out of the box with sensible defaults
Flexible Architecture: Object pooling for high-performance scenarios
DI-First Design: Seamless ASP.NET Core integration with named configurations
Comprehensive File Support: Upload and download files with minimal code
Smart Error Handling: Conditional error handling with fallback support
Installation
dotnet add package Myth.Rest
Quick Start
Simple GET Request
var response = await Rest
.Create()
.Configure(config => config
.WithBaseUrl("https://api.github.com")
.WithHeader("User-Agent", "Myth.Rest"))
.DoGet("users/octocat")
.OnResult(result => result.UseTypeForSuccess<User>())
.OnError(error => error.ThrowForNonSuccess())
.BuildAsync();
var user = response.GetAs<User>();
POST Request with Body
var newUser = new CreateUserRequest {
Name = "John Doe",
Email = "john@example.com"
};
var response = await Rest
.Create()
.Configure(config => config
.WithBaseUrl("https://api.example.com")
.WithBearerAuthorization(token))
.DoPost("users", newUser)
.OnResult(result => result
.UseTypeFor<User>(HttpStatusCode.Created)
.UseTypeFor<ValidationError>(HttpStatusCode.BadRequest))
.OnError(error => error.ThrowForNonSuccess())
.BuildAsync();
var user = response.GetAs<User>();
Dependency Injection
Basic Registration
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRest(config => config
.WithBaseUrl("https://api.example.com")
.WithBearerAuthorization(builder.Configuration["ApiToken"])
.WithRetry());
var app = builder.Build();
Using in Services
public class UserService
{
private readonly IRestRequest _restClient;
public UserService(IRestRequest restClient)
{
_restClient = restClient;
}
public async Task<User> GetUserAsync(int id, CancellationToken cancellationToken = default)
{
var response = await _restClient
.DoGet($"users/{id}")
.OnResult(r => r.UseTypeForSuccess<User>())
.OnError(e => e.ThrowForNonSuccess())
.BuildAsync(cancellationToken);
return response.GetAs<User>();
}
}
var response = await Rest
.Create()
.Configure(config => config
.WithBaseUrl("https://api.example.com")
.WithRetry())
.DoDownload("files/document.pdf")
.OnError(error => error.ThrowForNonSuccess())
.BuildAsync();
// Save to file
await response.SaveToFileAsync("./downloads", "document.pdf", replaceExisting: true);
// Or get as stream
var stream = response.ToStream();
// Or get as bytes
var bytes = response.ToByteArray();
Upload Files
From Stream
await using var fileStream = File.OpenRead("document.pdf");
var response = await Rest
.Create()
.Configure(config => config.WithBaseUrl("https://api.example.com"))
.DoUpload("files/upload", fileStream, "application/pdf")
.OnResult(r => r.UseTypeForSuccess<UploadResult>())
.BuildAsync();
From Byte Array
var fileBytes = File.ReadAllBytes("image.jpg");
.DoUpload("files/upload", fileBytes, "image/jpeg")
.OnError(error => error
.ThrowForNonSuccess() // Throw for any non-2xx status
.ThrowFor(HttpStatusCode.Unauthorized)
.NotThrowFor(HttpStatusCode.NotFound))
Conditional Error Handling
.OnError(error => error
.ThrowFor(HttpStatusCode.BadRequest,
body => body.errorCode == "VALIDATION_FAILED"))
Fallback Responses
Provide default responses for specific error scenarios:
.OnError(error => error
.UseFallback(HttpStatusCode.ServiceUnavailable, new {
message = "Service temporarily unavailable"
})
.UseFallback(HttpStatusCode.NotFound, new User {
Id = 0,
Name = "Unknown"
}))
public class ProductService
{
private readonly IRestFactory _factory;
private readonly ILogger<ProductService> _logger;
public ProductService(IRestFactory factory, ILogger<ProductService> logger)
{
_factory = factory;
_logger = logger;
}
public async Task<Product> GetProductAsync(string productId)
{
try
{
var response = await _factory
.Create("catalog")
.DoGet($"products/{productId}")
.OnResult(r => r.UseTypeForSuccess<Product>())
.OnError(e => e
.ThrowForNonSuccess()
.UseFallback(HttpStatusCode.ServiceUnavailable, new Product
{
Id = productId,
Name = "Product Unavailable",
Available = false
}))
.BuildAsync();
_logger.LogInformation(
"Retrieved product {ProductId} in {ElapsedTime}ms with {Retries} retries",
productId,
response.ElapsedTime.TotalMilliseconds,
response.RetriesMade);
return response.GetAs<Product>();
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to retrieve product {ProductId}", productId);
throw;
}
}
}
Response Metadata
Every response contains comprehensive metadata:
var response = await Rest.Create()...BuildAsync();
Console.WriteLine($"Status: {response.StatusCode}");
Console.WriteLine($"URL: {response.Url}");
Console.WriteLine($"Method: {response.Method}");
Console.WriteLine($"Elapsed Time: {response.ElapsedTime}");
Console.WriteLine($"Retries Made: {response.RetriesMade}");
Console.WriteLine($"Fallback Used: {response.FallbackUsed}");
Console.WriteLine($"Is Success: {response.IsSuccessStatusCode()}");
// Access results
var user = response.GetAs<User>(); // Typed result
var json = response.ToString(); // JSON string
var bytes = response.ToByteArray(); // Byte array
var stream = response.ToStream(); // Stream
dynamic dyn = response.DynamicResult; // Dynamic object
Exception Types
try
{
var response = await Rest.Create()...BuildAsync();
}
catch (NonSuccessException ex)
{
// HTTP error status codes
Console.WriteLine($"Status: {ex.Response.StatusCode}");
Console.WriteLine($"Content: {ex.Response}");
}
catch (NotMappedResultTypeException ex)
{
// No type mapping found for status code
Console.WriteLine($"Unmapped status: {ex.StatusCode}");
}
catch (DifferentResponseTypeException ex)
{
// Attempting to cast to wrong type
Console.WriteLine($"Expected: {ex.ExpectedType}, Actual: {ex.ActualType}");
}
catch (ParsingTypeException ex)
{
// JSON deserialization failed
Console.WriteLine($"Failed to parse: {ex.Content}");
}
catch (FileAlreadyExsistsOnDownloadException ex)
{
// File exists during download
Console.WriteLine($"File exists: {ex.FilePath}");
}
catch (NoActionMadeException)
{
// No HTTP action was defined
}
catch (CircuitBreakerOpenException ex)
{
// Circuit breaker is open
Console.WriteLine("Service circuit breaker is open");
}
Best Practices
Always Use Dependency Injection: Register REST clients as services for better testability and configuration management
Configure Retry Policies: Use retry policies in production for transient failure resilience
Implement Circuit Breakers: Prevent cascade failures in distributed systems
Use Named Configurations: Leverage the factory pattern when integrating with multiple APIs
Handle Errors Gracefully: Use fallbacks for non-critical operations
Leverage Strong Typing: Always map responses to strongly typed models
Configure Timeouts: Set appropriate timeouts based on your API characteristics
Enable Logging: Use structured logging for debugging and monitoring
Secure Sensitive Headers: Use specific authorization methods instead of manual headers for tokens
Use CancellationTokens: Always pass cancellation tokens to support request cancellation
Performance
Myth.Rest uses ObjectPool<RestBuilder> internally to minimize allocations and improve performance in high-throughput scenarios. The pooling is transparent and automatic.
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
)
