Albatross.Http

A companion library for HttpClient that simplifies building HTTP requests, executing them with typed error handling, and streaming responses. Designed for use with IHttpClientFactory and code-generated HTTP clients.

Key Features

• RequestBuilder - Fluent API for constructing HttpRequestMessage with JSON, text, stream, form, and multipart form data content.
• RequestBuilderExtensions - Extension methods for optional query string parameters with AddQueryStringIfSet<T>, including automatic ISO8601 formatting for date/time types.
• Typed Execute methods - Send requests and deserialize responses with automatic error handling via ServiceException<T>. Includes Send, Execute, ExecuteOrThrow, ExecuteOrThrowStruct, and ExecuteAsStream with simplified overloads that default the error type to string.
• Streaming support - ExecuteAsStream for consuming IAsyncEnumerable endpoints with true streaming via HttpCompletionOption.ResponseHeadersRead.
• URL utilities - Query string building, URL batching for large array parameters, relative URI resolution, and ISO8601 formatting helpers.
• DefaultJsonSerializerOptions - Shared JsonSerializerOptions with camelCase naming and null-ignoring behavior.
• Structured logging - LoggingHandler integrates with ILogger for HTTP request/response logging.

Quick Start

Install the package:

dotnet add package Albatross.Http

Build and execute a request:

using Albatross.Http;

// Build a request
var request = new RequestBuilder()
    .WithMethod(HttpMethod.Get)
    .WithRelativeUrl("api/items")
    .AddQueryString("category", "books")
    .Build();

// Execute with typed error handling
var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
var result = await httpClient.Execute<Item[]>(request, options, cancellationToken);

Stream results from an IAsyncEnumerable endpoint:

var request = new RequestBuilder()
    .WithMethod(HttpMethod.Get)
    .WithRelativeUrl("api/items/stream")
    .Build();

await foreach (var item in httpClient.ExecuteAsStream<Item, string>(request, options, cancellationToken)) {
    Console.WriteLine(item);
}

Register the logging handler with IHttpClientFactory:

services.AddTransient<LoggingHandler>();
services.AddHttpClient("MyApi")
    .AddHttpMessageHandler<LoggingHandler>();

Dependencies

• Microsoft.Extensions.Http 8.0.1
• Microsoft.Extensions.Logging.Abstractions 8.0.3
• System.Text.Json 8.0.6

Source Code

• https://github.com/RushuiGuan/http

Nuget Packages

Name	Version
Albatross.Http