RestEase

RestEase allows defining headers in four places: Interface Attributes, Interface Properties, Method Attributes, and Method Parameters. They are merged using these rules:

1. Interface Merging: Constant and Variable Interface headers are merged. If a header is defined both as an attribute and a property, the request will contain multiple values for that header.
2. Method Overriding: Method headers replace Interface headers. If a header name exists on both, the method-level definition wins.
3. Parameter Merging: Method headers and Method Parameters are merged.
4. Null Values: A header with a null value will not be added to the request, but it can be used to replace/remove a previously defined header of the same name.

RestEase's core logic resides in the IRequester interface. When you call RestClient.For<T>(), a generated class builds a RequestInfo object and passes it to an IRequester.

You can customize the entire request lifecycle by subclassing the default Requester implementation and providing your instance to RestClient.For<T>. The Requester class is designed to be easily extended by overriding its virtual methods.

Each RestEase interface implementation creates its own HttpClient instance.

• For .NET Core 2.1+: HttpClient handles connection pooling as expected. You can create and use interface instances freely.
• For older .NET versions: Avoid creating many HttpClient instances. Instead, create a single HttpClient and pass it to RestClient.For<T> to share it across multiple interface instances. This is particularly useful if you use properties (like Path or Header properties) that change frequently, as you can create many interface instances sharing one underlying client.

The final request path is constructed by concatenating three parts:

1. Base Address (e.g., https://api.example.com)
2. Base Path (optional, e.g., api/v1)
3. Method Path (from the [Get("path")] attribute)

Path Resolution Rules

• Method Path starts with /: The Base Path is ignored, but the Base Address is kept.
• Method Path is absolute (starts with http:// or https://): Both Base Address and Base Path are ignored.
• Base Path is absolute: The Base Address is ignored.

Configuring Base Address and Base Path

• Base Address: Can be set via RestClient.For<T>(uri), new RestClient(uri), by passing a configured HttpClient, or using the [BaseAddress(...)] attribute on the interface. If set via RestClient, the attribute is ignored.
• Base Path: Set using the [BasePath(...)] attribute on the interface.

If you want multiple RestEase interfaces to share the same underlying HttpClient configuration (like a shared BaseAddress), use the UseWithRestEaseClient<T> extension method on an IHttpClientBuilder.

To use this pattern:

1. Register a named HttpClient using AddHttpClient("name").
2. Configure the BaseAddress on that client.
3. Call .UseWithRestEaseClient<T>() for each interface you want to associate with that client.

services.AddHttpClient("example")
    .ConfigureHttpClient(x => x.BaseAddress = new Uri("https://api.example.com"))
    .UseWithRestEaseClient<ISomeApi>()
    .UseWithRestEaseClient<ISomeOtherApi>();

RestEase is available on NuGet. To use it in your project, install the RestEase package.

If you are using C# 9 or .NET 5 (or higher), it is recommended to also reference RestEase.SourceGenerator to enable compile-time errors and faster execution. This is also required if you are targeting platforms that do not support runtime code generation, such as iOS or .NET Native.

# Install the main package
dotnet add package RestEase

# Recommended for .NET 5+ or iOS/.NET Native
dotnet add package RestEase.SourceGenerator

To enable request cancellation, include a CancellationToken as one of the method parameters in your interface definition.

Note: If your method returns Task<HttpResponseMessage> or Task<Stream>, the CancellationToken will cancel the request initiation but will not cancel the download of the response body.

public interface ISomeApi
{
    [Get("very-large-response")]
    Task<LargeResponse> GetVeryLargeResponseAsync(CancellationToken cancellationToken);
}

To use custom serialization logic for path parameters (for example, to serialize Enums using their [Display] names), use PathSerializationMethod.Serialized in the [Path] attribute.

You must also provide a RequestPathParamSerializer implementation when initializing the RestClient.

public enum MyEnum
{
    [Display(Name = "first")]
    First,
    [Display(Name = "second")]
    Second,
}

public interface ISomeApi
{
    [Get("path/{param}")]
    Task<string> GetAsync([Path(PathSerializationMethod.Serialized)] MyEnum param);
}

ISomeApi api = new RestClient()
{
    RequestPathParamSerializer = new StringEnumRequestPathParamSerializer()
}.For<ISomeApi>("https://api.example.com");

// Requests https://api.example.com/path/first
await api.GetAsync(MyEnum.First);