ApiClient Library for .NET Core and .NET 5+ applications
A modern, resilient HTTP API client library for .NET Core and .NET 5+ applications, providing clean, async HTTP operations with built-in retry policies using Polly v8, comprehensive error handling, and structured logging support. Optimized for high-performance API consumption in cross-platform and cloud-native environments.
🎯 Features
Modern .NET Support: Built for .NET 6+ with nullable reference types
Polly v8 Integration: Flexible resilience pipelines with exponential backoff and jitter
Per-Instance HttpClient: Each ApiClient manages its own HttpClient for isolated configuration
Structured Logging: ILogger integration for comprehensive request/response logging
Flexible Authentication: Bearer, Basic, and API Key authentication support
Custom Headers Support: Add dynamic headers per request or globally
Thread-Safe Design: Proper concurrency handling with internal locking
Clean Architecture: SOLID principles with dependency injection support
Comprehensive Error Handling: Detailed error responses with HTTP status codes and timeout detection
Async/Await: Full asynchronous operation support with cancellation tokens
Configuration Validation: Prevents unsafe configuration changes after initialization
Relative Path Support: Built-in support for relative URLs with BaseAddress configuration
Streaming Performance: Efficient JSON deserialization using Newtonsoft.Json with streaming
ApiClient Library for .NET Core and .NET 5+ applications
A modern, resilient HTTP API client library for .NET Core and .NET 5+ applications, providing clean, async HTTP operations with built-in retry policies using Polly v8, comprehensive error handling, and structured logging support. Optimized for high-performance API consumption in cross-platform and cloud-native environments.
🎯 Features
Modern .NET Support: Built for .NET 6+ with nullable reference types
Polly v8 Integration: Built-in resilience pipelines with exponential backoff and jitter
Structured Logging: ILogger integration for comprehensive request/response logging
Multiple Auth Types: Bearer, Basic, and API Key authentication support
Clean Architecture: SOLID principles with dependency injection support
Comprehensive Error Handling: Detailed error responses with HTTP status codes
Async/Await: Full asynchronous operation support with cancellation tokens
Resource Management: Proper disposal support with optional HttpClient disposal
🚀 Quick Start
Installation
Add to your project via NuGet Package Manager or .csproj:
var jsonOptions = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase, // Default behavior
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
PropertyNameCaseInsensitive = true,
WriteIndented = false, // Compact JSON for better performance
Converters = { new JsonStringEnumConverter() } // Enum as strings
};
var apiClient = new ApiClient(httpClient, logger, jsonOptions);
Advanced Resilience Pipelines with Polly v8
// Simple retry with exponential backoff
var retryOptions = new RetryStrategyOptions<HttpResponseMessage>
{
MaxRetryAttempts = 3,
Delay = TimeSpan.FromSeconds(1),
BackoffType = DelayBackoffType.Exponential,
UseJitter = true
};
var retryPipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
.AddRetry(retryOptions)
.Build();
// Advanced retry with custom conditions
var advancedRetryOptions = new RetryStrategyOptions<HttpResponseMessage>
{
ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
.Handle<HttpRequestException>()
.Handle<TaskCanceledException>()
.HandleResult(r => !r.IsSuccessStatusCode || r.StatusCode == HttpStatusCode.TooManyRequests),
MaxRetryAttempts = 5,
Delay = TimeSpan.FromSeconds(2),
BackoffType = DelayBackoffType.Exponential,
UseJitter = true,
OnRetry = args =>
{
Console.WriteLine($"Retry {args.AttemptNumber} after {args.RetryDelay}");
return ValueTask.CompletedTask;
}
};
// Circuit breaker pattern
var circuitBreakerOptions = new CircuitBreakerStrategyOptions<HttpResponseMessage>
{
ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
.Handle<HttpRequestException>()
.HandleResult(r => r.StatusCode >= HttpStatusCode.InternalServerError),
FailureRatio = 0.3, // 30% failure rate
SamplingDuration = TimeSpan.FromSeconds(30),
MinimumThroughput = 10,
BreakDuration = TimeSpan.FromSeconds(60)
};
// Combine multiple strategies
var combinedPipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
.AddRetry(advancedRetryOptions)
.AddCircuitBreaker(circuitBreakerOptions)
.AddTimeout(TimeSpan.FromSeconds(30)) // Overall timeout
.Build();
var apiClient = new ApiClient(httpClient, logger, jsonOptions, combinedPipeline);
🛡️ Error Handling
Response Structure
public class ApiResponse<T>
{
public bool Success { get; set; } // Operation success status
public T? Data { get; set; } // Response data (if successful)
public string? ErrorMessage { get; set; } // Error description
public string? ErrorData { get; set; } // Raw error response
public HttpStatusCode StatusCode { get; set; } // HTTP status code
}
Error Handling Patterns
var response = await apiClient.GetAsync<User>(userUrl);
// Pattern 1: Simple success check
if (response.Success)
{
ProcessUser(response.Data!);
}
else
{
_logger.LogError("API call failed: {Error}", response.ErrorMessage);
}
// Pattern 2: Status code specific handling
switch (response.StatusCode)
{
case HttpStatusCode.OK:
ProcessUser(response.Data!);
break;
case HttpStatusCode.NotFound:
// Handle user not found
break;
case HttpStatusCode.Unauthorized:
// Refresh token or redirect to login
break;
case HttpStatusCode.TooManyRequests:
// Implement backoff (handled by retry policy)
break;
default:
_logger.LogError("Unexpected error {StatusCode}: {Error}",
response.StatusCode, response.ErrorMessage);
break;
}
// Pattern 3: Exception-based handling
public async Task<User> GetUserOrThrowAsync(int userId)
{
var response = await apiClient.GetAsync<User>(new Uri($"https://api.example.com/users/{userId}"));
return response.Success
? response.Data!
: throw new HttpRequestException($"Failed to get user {userId}: {response.ErrorMessage}");
}
📝 Logging Integration
The ApiClient integrates with Microsoft.Extensions.Logging for comprehensive request/response logging:
// The ApiClient automatically logs errors during HTTP requests
// Configure logging levels in appsettings.json
{
"Logging": {
"LogLevel": {
"Default": "Information",
"ARSoft.ApiClient.ApiClient": "Debug"
}
}
}
🧪 Testing
Unit Testing with Mock
[Test]
public async Task GetAsync_Success_ReturnsData()
{
// Arrange
var mockHandler = new Mock<HttpMessageHandler>();
var mockLogger = new Mock<ILogger<ApiClient>>();
var expectedResponse = new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent(JsonSerializer.Serialize(new User { Id = 1, Name = "Test User" }))
};
mockHandler.Protected()
.Setup<Task<HttpResponseMessage>>(
"SendAsync",
ItExpr.IsAny<HttpRequestMessage>(),
ItExpr.IsAny<CancellationToken>())
.ReturnsAsync(expectedResponse);
var httpClient = new HttpClient(mockHandler.Object);
var apiClient = new ApiClient(httpClient, mockLogger.Object, disposeHttpClient: true);
// Act
var result = await apiClient.GetAsync<User>(new Uri("https://api.test.com/users/1"));
// Assert
Assert.IsTrue(result.Success);
Assert.AreEqual("Test User", result.Data!.Name);
}
Integration Testing
[TestFixture]
public class ApiClientIntegrationTests
{
private IApiClient _apiClient = null!;
[SetUp]
public void Setup()
{
var httpClient = new HttpClient();
var logger = new Mock<ILogger<ApiClient>>().Object;
_apiClient = new ApiClient(httpClient, logger, disposeHttpClient: true);
}
[Test]
public async Task GetAsync_RealApi_Success()
{
// Test against a real API endpoint
var response = await _apiClient.GetAsync<JsonElement>(
new Uri("https://jsonplaceholder.typicode.com/posts/1"));
Assert.IsTrue(response.Success);
Assert.IsNotNull(response.Data);
}
[TearDown]
public void TearDown()
{
_apiClient?.Dispose();
}
}