ZeroAlloc.Rest.SystemTextJson 1.0.1

ZeroAlloc.Rest

ZeroAlloc.Rest is a source-generated, Native AOT-compatible REST client for .NET 10+. Define your HTTP API as a C# interface — the Roslyn generator emits a fully type-safe, zero-reflection implementation at compile time. No runtime code generation, no IL emit, no allocations beyond the HTTP layer itself.

Install

dotnet add package ZeroAlloc.Rest
dotnet add package ZeroAlloc.Rest.Generator
dotnet add package ZeroAlloc.Rest.SystemTextJson

Or via <PackageReference>:

<PackageReference Include="ZeroAlloc.Rest" Version="x.y.z" />
<PackageReference Include="ZeroAlloc.Rest.Generator"
                  Version="x.y.z"
                  OutputItemType="Analyzer"
                  ReferenceOutputAssembly="false" />
<PackageReference Include="ZeroAlloc.Rest.SystemTextJson" Version="x.y.z" />

Optional: resilience policies

To add retry, timeout, and circuit-breaker behaviour to a client, install the bridge package alongside ZeroAlloc.Resilience:

dotnet add package ZeroAlloc.Rest.Resilience
dotnet add package ZeroAlloc.Resilience
dotnet add package ZeroAlloc.Resilience.Generator  # analyzer reference

Quick Start

1. Define your API interface:

using ZeroAlloc.Rest.Attributes;

[ZeroAllocRestClient]
public interface IUserApi
{
    [Get("/users/{id}")]
    Task<UserDto> GetUserAsync(int id, CancellationToken ct = default);

    [Get("/users")]
    Task<List<UserDto>> ListUsersAsync([Query] string? name = null, CancellationToken ct = default);

    [Post("/users")]
    Task<UserDto> CreateUserAsync([Body] CreateUserRequest request, CancellationToken ct = default);

    [Delete("/users/{id}")]
    Task DeleteUserAsync(int id, CancellationToken ct = default);
}

2. Register in DI:

builder.Services.AddIUserApi(options =>
{
    options.BaseAddress = new Uri("https://api.example.com");
    options.UseSerializer<SystemTextJsonSerializer>();
});

3. Inject and use:

public class UserService(IUserApi api)
{
    public Task<UserDto> GetAsync(int id) => api.GetUserAsync(id);
}

The generator produces UserApiClient — a sealed class implementing IUserApi — at compile time. No reflection, no proxies, no DynamicMethod.

Performance

Measured on .NET 10.0.4, Windows 11, X64. In-memory handler; no real network I/O. See docs/benchmarks.md for methodology and full results.

Features

• Source-generated — zero runtime reflection; compile-time type safety
• Native AOT compatible — no DynamicMethod, no IL emit, no Type.GetType
• Per-method serializer override — [Serializer(typeof(MySerializer))] for mixed protocols
• Path, query, body, and header parameters — {id}, [Query], [Body], [Header("X-Api-Key")]
• Result<T, HttpError> — typed success/error returns via ZeroAlloc.Results; no exception-throwing on 4xx/5xx
• OpenAPI code generation — OpenApiInterfaceGenerator API + MSBuild <ZeroAllocApiSpec> task
• Pluggable serializers — System.Text.Json, MemoryPack, MessagePack, or bring your own
• IHttpClientFactory integration — AddI{Interface} generated extension method
• Resilience bridge — ZeroAlloc.Rest.Resilience wraps any client with [Retry], [Timeout], [CircuitBreaker], and [RateLimit] via AddRestResilience<,,>()

Telemetry

Every generated client emits OpenTelemetry-compatible signals out of the box, with no extra dependency beyond the BCL System.Diagnostics primitives.

Tracing. An ActivitySource("ZeroAlloc.Rest") produces one span per call, named Interface.Method. Tags: http.method, http.status_code, server.address, rest.method. Exceptions set ActivityStatusCode.Error with the message.

Metrics. The generator emits rest.requests_total (counter) and rest.request_duration_ms (histogram) under the ZeroAlloc.Rest Meter. Tags: http.method, http.status_code, server.address, rest.method (the generated Interface.Method identifier).

The counter is incremented only on the success path. On exception, the histogram records the elapsed duration but the counter is left untouched — this lets operators distinguish failed attempts via histogram count vs. counter delta. The exception-path histogram carries only http.method and rest.method, since http.status_code and server.address may not be known.

Subscription:

services.AddOpenTelemetry()
        .WithTracing(t => t.AddSource("ZeroAlloc.Rest"))
        .WithMetrics(m => m.AddMeter("ZeroAlloc.Rest"));

Documentation

License

MIT