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: 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
🚀 Quick Start
Installation
Add to your project via NuGet Package Manager or .csproj:
// Create client with base address
var apiClient = new ApiClient(
baseAddress: new Uri("https://api.example.com"),
timeout: TimeSpan.FromSeconds(30));
// Make requests using relative paths
var response = await apiClient.GetAsync<User>("users/1");
if (response.Success)
{
Console.WriteLine($"User: {response.Data.Name}");
}
Dependency Injection Setup
// Program.cs - ASP.NET Core
builder.Services.AddSingleton<IApiClient>(sp =>
{
var logger = sp.GetRequiredService<ILogger<ApiClient>>();
var client = new ApiClient(
baseAddress: new Uri("https://api.example.com"),
timeout: TimeSpan.FromSeconds(60),
logger: logger);
// Add default headers before first use
client.AddDefaultRequestHeader("User-Agent", "MyApp/1.0");
client.AddDefaultRequestHeader("Accept-Language", "en-US");
return client;
});
📋 Detailed Examples
1. GET Request with Relative Paths
public class UserService
{
private readonly IApiClient _apiClient;
private readonly ILogger<UserService> _logger;
public UserService(IApiClient apiClient, ILogger<UserService> logger)
{
_apiClient = apiClient;
_logger = logger;
}
public async Task<List<User>> GetUsersAsync(string bearerToken, CancellationToken cancellationToken = default)
{
// Using relative path with configured BaseAddress
var response = await _apiClient.GetAsync<List<User>>(
"users",
authToken: bearerToken,
authType: AuthType.Bearer,
cancellationToken: cancellationToken);
if (response.Success)
{
_logger.LogInformation("Retrieved {Count} users", response.Data?.Count ?? 0);
return response.Data ?? new List<User>();
}
_logger.LogError("Failed to retrieve users: {Error}", response.ErrorMessage);
throw new HttpRequestException($"Failed to get users: {response.ErrorMessage}");
}
public async Task<User> GetUserByIdAsync(int userId)
{
// Absolute URI also supported
var response = await _apiClient.GetAsync<User>(
new Uri($"https://api.example.com/users/{userId}"));
return response.Data!;
}
}
2. Using Custom Headers Per Request
public class ApiService
{
private readonly IApiClient _apiClient;
public ApiService(IApiClient apiClient)
{
_apiClient = apiClient;
}
// Example 1: Request-specific tracing header
public async Task<Order> GetOrderAsync(string orderId, string traceId)
{
var customHeaders = new Dictionary<string, string>
{
{ "X-Trace-Id", traceId },
{ "X-Request-Source", "Mobile-App" }
};
var response = await _apiClient.GetAsync<Order>(
new Uri($"https://api.orders.com/orders/{orderId}"),
customHeaders: customHeaders);
return response.Data!;
}
// Example 2: API versioning with custom header
public async Task<Product> GetProductV2Async(int productId)
{
var headers = new Dictionary<string, string>
{
{ "X-API-Version", "2.0" },
{ "X-Feature-Flags", "new-pricing,bulk-discount" }
};
var response = await _apiClient.GetAsync<Product>(
$"products/{productId}",
customHeaders: headers);
return response.Data!;
}
// Example 3: Combining authentication with custom headers
public async Task<Report> GenerateReportAsync(string apiKey, string reportType, string format)
{
var customHeaders = new Dictionary<string, string>
{
{ "X-Report-Type", reportType },
{ "X-Output-Format", format },
{ "X-Request-Priority", "high" }
};
var response = await _apiClient.GetAsync<Report>(
new Uri("https://api.analytics.com/reports/generate"),
authToken: apiKey,
authType: AuthType.ApiKey,
customHeaders: customHeaders);
return response.Data!;
}
}
public record Order(string Id, decimal Total, DateTime CreatedAt);
public record Product(int Id, string Name, decimal Price);
public record Report(string Id, byte[] Data, string Format);
3. POST Request with Custom Headers
public class PaymentService
{
private readonly IApiClient _apiClient;
public PaymentService(IApiClient apiClient)
{
_apiClient = apiClient;
}
public async Task<PaymentResult> ProcessPaymentAsync(PaymentRequest payment, string idempotencyKey)
{
// Idempotency key prevents duplicate charges
var customHeaders = new Dictionary<string, string>
{
{ "X-Idempotency-Key", idempotencyKey },
{ "X-Client-Version", "1.2.3" },
{ "X-Device-Id", Environment.MachineName }
};
var response = await _apiClient.PostAsync<PaymentRequest, PaymentResult>(
new Uri("https://api.payments.com/v1/charge"),
payload: payment,
authToken: "sk_live_xyz123",
authType: AuthType.ApiKey,
customHeaders: customHeaders);
if (!response.Success)
{
throw new PaymentException($"Payment failed: {response.ErrorMessage}");
}
return response.Data!;
}
}
public record PaymentRequest(decimal Amount, string Currency, string CardToken);
public record PaymentResult(string TransactionId, string Status, DateTime ProcessedAt);
public class PaymentException : Exception
{
public PaymentException(string message) : base(message) { }
}
4. Advanced Configuration with Default and Custom Headers
public class EnterpriseApiClient
{
private readonly IApiClient _apiClient;
public EnterpriseApiClient(ILogger<ApiClient> logger, string environment)
{
_apiClient = new ApiClient(
baseAddress: new Uri("https://api.enterprise.com"),
timeout: TimeSpan.FromSeconds(120),
logger: logger);
// Set default headers that apply to ALL requests
_apiClient.AddDefaultRequestHeader("X-Environment", environment);
_apiClient.AddDefaultRequestHeader("X-Client-Type", "EnterpriseClient");
_apiClient.AddDefaultRequestHeader("User-Agent", "EnterpriseApp/2.0");
}
public async Task<Customer> CreateCustomerAsync(
CreateCustomerRequest request,
string apiKey,
string correlationId)
{
// These custom headers are ONLY for this specific request
var requestHeaders = new Dictionary<string, string>
{
{ "X-Correlation-Id", correlationId },
{ "X-Operation", "CreateCustomer" },
{ "X-Request-Timestamp", DateTime.UtcNow.ToString("o") }
};
var response = await _apiClient.PostAsync<CreateCustomerRequest, Customer>(
new Uri("customers", UriKind.Relative),
payload: request,
authToken: apiKey,
authType: AuthType.ApiKey,
customHeaders: requestHeaders);
return response.Data!;
}
// Headers can be built dynamically based on context
public async Task<List<Transaction>> GetTransactionsAsync(
string accountId,
string userId,
TransactionQueryOptions options)
{
var headers = new Dictionary<string, string>
{
{ "X-User-Id", userId },
{ "X-Account-Id", accountId }
};
// Add conditional headers based on options
if (options.IncludeMetadata)
{
headers["X-Include-Metadata"] = "true";
}
if (options.PageSize.HasValue)
{
headers["X-Page-Size"] = options.PageSize.Value.ToString();
}
var response = await _apiClient.GetAsync<List<Transaction>>(
$"accounts/{accountId}/transactions",
customHeaders: headers);
return response.Data ?? new List<Transaction>();
}
}
public record CreateCustomerRequest(string Name, string Email);
public record Customer(string Id, string Name, string Email);
public record Transaction(string Id, decimal Amount, DateTime Date);
public record TransactionQueryOptions(bool IncludeMetadata, int? PageSize);
var jsonSettings = new JsonSerializerSettings
{
ContractResolver = new CamelCasePropertyNamesContractResolver(),
NullValueHandling = NullValueHandling.Ignore,
Formatting = Formatting.None,
DateFormatHandling = DateFormatHandling.IsoDateFormat,
Converters = new List<JsonConverter>
{
new StringEnumConverter()
}
};
var apiClient = new ApiClient(
baseAddress: new Uri("https://api.example.com"),
jsonSettings: jsonSettings);
Advanced Resilience Pipelines with Polly v8
// Custom retry pipeline with exponential backoff
var retryOptions = new RetryStrategyOptions<HttpResponseMessage>
{
MaxRetryAttempts = 3,
Delay = TimeSpan.FromMilliseconds(500),
BackoffType = DelayBackoffType.Exponential,
UseJitter = true,
ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
.Handle<HttpRequestException>()
.Handle<TaskCanceledException>(ex => !ex.CancellationToken.IsCancellationRequested)
.HandleResult(r => r.StatusCode is
HttpStatusCode.RequestTimeout or
HttpStatusCode.TooManyRequests or
HttpStatusCode.ServiceUnavailable or
HttpStatusCode.GatewayTimeout),
OnRetry = args =>
{
Console.WriteLine($"Retry {args.AttemptNumber} after {args.RetryDelay}");
return ValueTask.CompletedTask;
}
};
var resiliencePipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
.AddRetry(retryOptions)
.Build();
var apiClient = new ApiClient(
baseAddress: new Uri("https://api.example.com"),
resiliencePipeline: resiliencePipeline);
No Retry Pipeline (High-Performance Scenarios)
// For scenarios where retries are not desired (e.g., idempotent operations handled elsewhere)
var noRetryPipeline = ApiClient.CreateNoRetryPipeline();
var apiClient = new ApiClient(
baseAddress: new Uri("https://api.example.com"),
resiliencePipeline: noRetryPipeline);
Default Light Retry Pipeline
The library includes a sensible default retry pipeline that handles transient failures:
Max Retry Attempts: 2
Delay: 300ms with exponential backoff
Jitter: Enabled to prevent thundering herd
Retry Conditions:
HttpRequestException (network failures)
TaskCanceledException when NOT cancelled by user (timeout scenarios)
HTTP 408 (Request Timeout)
HTTP 429 (Too Many Requests)
HTTP 503 (Service Unavailable)
HTTP 504 (Gateway Timeout)
🛡️ 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>("users/123");
// 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:
// Rate limit exceeded
break;
default:
_logger.LogError("Unexpected error {StatusCode}: {Error}",
response.StatusCode, response.ErrorMessage);
break;
}
// Pattern 3: Timeout detection
if (!response.Success && response.ErrorMessage == "Request timeout")
{
_logger.LogWarning("Request timed out, consider increasing timeout or checking network");
}
// Pattern 4: Exception-based handling
public async Task<User> GetUserOrThrowAsync(int userId)
{
var response = await apiClient.GetAsync<User>($"users/{userId}");
return response.Success
? response.Data!
: throw new HttpRequestException(
$"Failed to get user {userId}: {response.ErrorMessage}");
}
Timeout Handling
The library distinguishes between user-initiated cancellation and timeout:
try
{
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var response = await apiClient.GetAsync<Data>("data", cancellationToken: cts.Token);
if (!response.Success)
{
if (response.ErrorMessage == "Request timeout")
{
// HttpClient timeout exceeded
Console.WriteLine("Server took too long to respond");
}
else if (response.ErrorMessage == "Request cancelled")
{
// User cancelled via CancellationToken
Console.WriteLine("Request was cancelled by user");
}
}
}
catch (OperationCanceledException)
{
// This won't normally occur as cancellation is handled internally
Console.WriteLine("Operation was cancelled");
}
🔒 Configuration Safety
Configuration Lock Mechanism
The ApiClient prevents configuration changes after the first request is sent to ensure thread-safety and predictable behavior:
var client = new ApiClient(new Uri("https://api.example.com"));
// ✅ OK - Before first request
client.AddDefaultRequestHeader("X-Custom", "value");
client.SetTimeout(TimeSpan.FromSeconds(30));
// Send first request
await client.GetAsync<Data>("data");
// ❌ THROWS ApiClientConfigurationException - After first request
try
{
client.SetTimeout(TimeSpan.FromSeconds(60));
}
catch (ApiClientConfigurationException ex)
{
Console.WriteLine($"Configuration error: {ex.Reason}");
// Output: Configuration error: TimeoutModificationNotAllowed
}
ApiClientConfigurationException
public enum ApiClientConfigurationReason
{
HeadersModificationNotAllowed,
BaseAddressModificationNotAllowed,
TimeoutModificationNotAllowed,
ClientDisposed
}
// Example handling
try
{
client.AddDefaultRequestHeader("X-New-Header", "value");
}
catch (ApiClientConfigurationException ex) when
(ex.Reason == ApiClientConfigurationReason.HeadersModificationNotAllowed)
{
// Handle configuration lock
_logger.LogWarning("Cannot modify headers after requests have been sent");
}
📝 Logging Integration
The ApiClient integrates with Microsoft.Extensions.Logging:
[Test]
public async Task GetAsync_WithCustomHeaders_Success()
{
// Arrange
var mockHandler = new Mock<HttpMessageHandler>();
var expectedResponse = new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent(JsonConvert.SerializeObject(
new User { Id = 1, Name = "Test User" }))
};
mockHandler.Protected()
.Setup<Task<HttpResponseMessage>>(
"SendAsync",
ItExpr.Is<HttpRequestMessage>(req =>
req.Headers.Contains("X-Custom-Header")),
ItExpr.IsAny<CancellationToken>())
.ReturnsAsync(expectedResponse);
var apiClient = new ApiClient(new Uri("https://api.test.com"));
// Act
var headers = new Dictionary<string, string>
{
{ "X-Custom-Header", "test-value" }
};
var result = await apiClient.GetAsync<User>(
"users/1",
customHeaders: headers);
// Assert
Assert.IsTrue(result.Success);
Assert.AreEqual("Test User", result.Data!.Name);
}
📦 Package Information
Dependencies
.NET 6+ (with nullable reference types support)
Newtonsoft.Json 13.0.3+
Polly 8.6.2+
Polly.Core 8.6.2+
Microsoft.Extensions.Logging.Abstractions 9.0.0+
Performance Benefits
Newtonsoft.Json with Streaming: High-performance JSON deserialization using StreamReader and JsonTextReader
Per-Instance HttpClient: Isolated configuration prevents cross-contamination between different client instances
HTTP Connection Pooling: Efficient connection reuse within each client
Added comprehensive documentation for multi-tenant, webhook, and rate-limiting scenarios
Updated all method signatures to support Dictionary<string, string>? customHeaders
v3.1.1
Breaking Change: Removed constructor parameter for external HttpClient
Added internal shared HttpClient managed by library
Added ApiClientConfigurationException for post-start configuration changes
Improved concurrency and memory safety
Enhanced XML documentation for all public members
Internal locking for thread-safe configuration state
v3.1.0
New Feature: Custom authentication type support
Added CustomAuthInfo record for flexible header configuration
Enhanced authentication flexibility
v3.0.4
JsonSerializerOptions default settings improved
Constructor summary comments added for better IntelliSense support
v3.0.0
Breaking Changes: Migrated to Polly v8 with ResiliencePipeline
Updated to use modern Polly.Core
Improved nullable reference types support
Enhanced error handling and logging
Added proper resource disposal support
Simplified configuration with default retry strategies
Migration Notes
From v3.2.0 to v3.3.0
IMPORTANT: ApiClient no longer shares a static HttpClient. Each instance has its own.
Impact: If you were relying on shared configuration across instances, you'll need to adjust your code.
Recommendation: Use dependency injection with singleton ApiClient instances for each base URL.
New Feature: Can now use relative paths: GetAsync<T>("users/1") instead of always using full URIs.
JSON Library: Now uses Newtonsoft.Json instead of System.Text.Json (more stable for complex scenarios).
Example migration:
// Before (v3.2.0) - shared static HttpClient
var client1 = new ApiClient(timeout: TimeSpan.FromSeconds(30));
var client2 = new ApiClient(timeout: TimeSpan.FromSeconds(15));
// client2 would affect client1's timeout ❌
// After (v3.3.0) - isolated HttpClients
var client1 = new ApiClient(timeout: TimeSpan.FromSeconds(30));
var client2 = new ApiClient(timeout: TimeSpan.FromSeconds(15));
// Each has independent configuration ✅
From v3.1.x to v3.2.0
Replace CustomAuthInfo usage with customHeaders dictionary