API Reference

Complete reference documentation for WebSpark.HttpClientUtility.

Core Interfaces

IHttpRequestResultService

Main interface for making HTTP requests.

public interface IHttpRequestResultService
{
    Task<HttpRequestResult<T>> HttpSendRequestResultAsync<T>(
        HttpRequestResult<T> request,
        CancellationToken cancellationToken = default);
}

Methods:

Core Classes

HttpRequestResult<T>

Represents an HTTP request and its response.

public class HttpRequestResult<T>
{
    // Request Properties
    public string RequestPath { get; set; }
    public HttpMethod RequestMethod { get; set; }
    public object? RequestBody { get; set; }
    public Dictionary<string, string>? RequestHeaders { get; set; }
    public string? CorrelationId { get; set; }
    
    // Caching
    public int CacheDurationMinutes { get; set; }
    
    // Authentication
    public IAuthenticationProvider? AuthenticationProvider { get; set; }
    
    // Response Properties (populated after request)
    public T? ResponseResults { get; set; }
    public string? ResponseContent { get; set; }
    public HttpStatusCode StatusCode { get; set; }
    public bool IsSuccessStatusCode { get; set; }
    public long RequestDuration { get; set; }
    public Dictionary<string, IEnumerable<string>>? ResponseHeaders { get; set; }
}

Key Properties:

Property Type Description
RequestPath string The URL to send the request to
RequestMethod HttpMethod HTTP method (GET, POST, PUT, DELETE, etc.)
RequestBody object? Request body object (serialized to JSON)
RequestHeaders Dictionary<string, string>? Custom headers to include
CorrelationId string? Tracking ID (auto-generated if not provided)
CacheDurationMinutes int Cache duration in minutes (0 = no cache)
AuthenticationProvider IAuthenticationProvider? Authentication provider
ResponseResults T? Deserialized response object
ResponseContent string? Raw response content
StatusCode HttpStatusCode HTTP status code
IsSuccessStatusCode bool True if status code is 2xx
RequestDuration long Request duration in milliseconds

Service Registration Extensions

ServiceCollectionExtensions

Extension methods for configuring services.

public static class ServiceCollectionExtensions
{
    // Basic registration
    public static IServiceCollection AddHttpClientUtility(
        this IServiceCollection services);

    // With configuration
    public static IServiceCollection AddHttpClientUtility(
        this IServiceCollection services,
        Action<HttpClientUtilityOptions> configure);

    // Quick setups
    public static IServiceCollection AddHttpClientUtilityWithCaching(
        this IServiceCollection services);

    public static IServiceCollection AddHttpClientUtilityWithAllFeatures(
        this IServiceCollection services);
}

HttpClientUtilityOptions

Configuration options for the library.

public class HttpClientUtilityOptions
{
    public bool EnableCaching { get; set; } = false;
    public bool EnableResilience { get; set; } = false;
    public bool EnableTelemetry { get; set; } = false;
    public HttpRequestResultPollyOptions ResilienceOptions { get; set; }
}

HttpRequestResultPollyOptions

Resilience configuration options.

public class HttpRequestResultPollyOptions
{
    public int MaxRetryAttempts { get; set; } = 3;
    public TimeSpan RetryDelay { get; set; } = TimeSpan.FromSeconds(1);
    public int CircuitBreakerThreshold { get; set; } = 5;
    public TimeSpan CircuitBreakerDuration { get; set; } = TimeSpan.FromSeconds(30);
}

Authentication

IAuthenticationProvider

Interface for authentication providers.

public interface IAuthenticationProvider
{
    Task ApplyAuthenticationAsync(HttpRequestMessage request);
}

BearerTokenAuthenticationProvider

Bearer token authentication.

public class BearerTokenAuthenticationProvider : IAuthenticationProvider
{
    public BearerTokenAuthenticationProvider(string token);
    public Task ApplyAuthenticationAsync(HttpRequestMessage request);
}

BasicAuthenticationProvider

Basic authentication (username/password).

public class BasicAuthenticationProvider : IAuthenticationProvider
{
    public BasicAuthenticationProvider(string username, string password);
    public Task ApplyAuthenticationAsync(HttpRequestMessage request);
}

ApiKeyAuthenticationProvider

API key authentication.

public class ApiKeyAuthenticationProvider : IAuthenticationProvider
{
    public ApiKeyAuthenticationProvider(string headerName, string apiKey);
    public Task ApplyAuthenticationAsync(HttpRequestMessage request);
}

Web Crawling

CrawlerOptions

Configuration for web crawler.

public class CrawlerOptions
{
    public string BaseUrl { get; set; }
    public int MaxDepth { get; set; } = 3;
    public int MaxPages { get; set; } = 100;
    public bool RespectRobotsTxt { get; set; } = true;
    public string UserAgent { get; set; } = "WebSparkCrawler/1.0";
    public TimeSpan DelayBetweenRequests { get; set; } = TimeSpan.FromMilliseconds(500);
}

SiteCrawler

Web crawler implementation.

public class SiteCrawler
{
    public SiteCrawler(
        CrawlerOptions options,
        IHttpRequestResultService httpService,
        ILogger<SiteCrawler> logger);

    public Task CrawlAsync(CancellationToken cancellationToken = default);
    
    public event EventHandler<PageCrawledEventArgs>? PageCrawled;
    public event EventHandler<CrawlProgressEventArgs>? CrawlProgress;
}

Events:

Utilities

QueryStringParametersList

Helper for building query strings.

public class QueryStringParametersList : List<KeyValuePair<string, string>>
{
    public void Add(string key, string value);
    public string ToQueryString();
}

Example:

var queryParams = new QueryStringParametersList
{
    { "page", "1" },
    { "pageSize", "50" }
};

var queryString = queryParams.ToQueryString(); // "?page=1&pageSize=50"

HttpResponse

Response wrapper class.

public class HttpResponse
{
    public HttpStatusCode StatusCode { get; set; }
    public string? Content { get; set; }
    public Dictionary<string, IEnumerable<string>>? Headers { get; set; }
    public bool IsSuccessStatusCode { get; set; }
}

Testing

MockHttpRequestResultService<T>

Mock service for unit testing.

public class MockHttpRequestResultService<T> : IHttpRequestResultService
{
    public MockHttpRequestResultService(HttpResponseMessage response);
    public MockHttpRequestResultService(T responseData, HttpStatusCode statusCode = HttpStatusCode.OK);
    
    public Task<HttpRequestResult<T>> HttpSendRequestResultAsync<T>(
        HttpRequestResult<T> request,
        CancellationToken cancellationToken = default);
}

Concurrent Requests

IConcurrentHttpService

Interface for concurrent request execution.

public interface IConcurrentHttpService
{
    Task<IEnumerable<HttpRequestResult<T>>> ExecuteConcurrentRequestsAsync<T>(
        IEnumerable<HttpRequestResult<T>> requests,
        CancellationToken cancellationToken = default);
}

OpenTelemetry Integration

OpenTelemetry Extensions

public static class OpenTelemetryExtensions
{
    public static IServiceCollection AddWebSparkOpenTelemetry(
        this IServiceCollection services,
        Action<TracerProviderBuilder>? configure = null);
}

Common Status Codes

Code Enum Description
200 HttpStatusCode.OK Success
201 HttpStatusCode.Created Resource created
204 HttpStatusCode.NoContent Success with no content
400 HttpStatusCode.BadRequest Invalid request
401 HttpStatusCode.Unauthorized Authentication required
403 HttpStatusCode.Forbidden Access denied
404 HttpStatusCode.NotFound Resource not found
500 HttpStatusCode.InternalServerError Server error
503 HttpStatusCode.ServiceUnavailable Service unavailable

Framework Targets

NuGet Package

Source Code

View the complete source code and contribute on GitHub.

Next Steps

View Examples Get Started