WebApiClient Documentation

WebApiClient provides several core capabilities for building REST clients:

• Semantic Declarations: Define clients by simply declaring interfaces.
• Diverse Serialization: Supports JSON, XML, Form, and custom serialization methods.
• AOT & Trimming: Fully supports .NET 8 code trimming and Ahead-of-Time (AOT) compilation.
• Aspect-Oriented Programming (AOP): Supports interceptors, filters, logging, retries, and custom caching.
• Syntax Analysis: Provides syntax analysis and hints for interface declarations to prevent incorrect usage.
• Authentication Support: Includes extension packages for OAuth2 and token management to simplify identity authentication and authorization.
• Automatic Code Generation: A dotnet tool can parse local or remote OpenAPI documents to automatically generate WebApiClientCore interface code.
• High Performance: Benchmarked to be up to 2.X times faster than Refit in various request scenarios.

While Task<T> is suitable for simple requests, use ITask<T> when you need conditional retries or specialized error handling.

Retry Strategies

• Basic: task.Retry(count)
• Fixed Delay: task.Retry(count, TimeSpan)
• Dynamic/Exponential Backoff: task.Retry(count, index => TimeSpan)

Error and Result Handling

• WhenCatch<TException>: Catch specific exceptions to trigger retries or log errors.
• WhenResult: Trigger retries based on the success/failure of the returned result.
• HandleAsDefaultWhenException: Return a default value if an exception occurs.
• Handle: Provide a fallback mechanism using WhenCatch.

using WebApiClientCore;

// Basic retry
ITask<T> task = api.GetAsync(id);
await task.Retry(3);

// Fixed delay
await api.GetAsync(id).Retry(3, TimeSpan.FromSeconds(1));

// Dynamic delay (exponential backoff)
await api.GetAsync(id).Retry(3, i => TimeSpan.FromSeconds(Math.Pow(2, i)));

// Catching exceptions
await api.GetAsync(id)
    .Retry(3)
    .WhenCatch<HttpRequestException>()                               // Catch and retry
    .WhenCatch<HttpRequestException>(ex => logger.LogWarning(ex))    // Catch and log
    .WhenCatch<HttpRequestException>(ex => ex.InnerException is SocketException);  // Conditional catch

// Result-based retry
await api.GetAsync(id)
    .Retry(3)
    .WhenResult(r => r.Success == false)
    .WhenResultAsync(async r => await cacheService.IsStaleAsync(r.Version));

// Handling exceptions with defaults
var user = await api.GetAsync(id).HandleAsDefaultWhenException();

var result = await api.GetAsync(id)
    .Handle()
    .WhenCatch<HttpRequestException>(() => new User { Id = "error" });

Return attributes define how the response content is mapped to .NET data models.

Rules for Return Attributes:

1. Content-Type Matching: If EnsureMatchAcceptContentType is true (default), the attribute only applies if the response Content-Type matches the attribute's AcceptContentType.
2. Error Handling: If no Return attribute matches the response Content-Type, an ApiReturnNotSupportedException is thrown.
3. Status Code Validation: If EnsureSuccessStatusCode is true (default), an ApiResponseStatusException is thrown if the status code is not in the 200-299 range.
4. Priority: If multiple attributes have the same AcceptContentType, the one with the highest AcceptQuality is used.

Implicit Defaults: Every interface has implicit Return attributes with AcceptQuality = 0.1. To override them, declare a new attribute of the same type with a higher AcceptQuality.

Available Return Attributes:

• [RawReturn]: Supports string, byte[], Stream, and HttpResponseMessage.
• [JsonReturn]: Uses System.Text.Json for serialization/deserialization.
• [XmlReturn]: Uses System.Xml.Serialization for serialization/deserialization.
• [NoneReturn]: If the response status is 204, returns the default value of the return type.

[Json] // .AcceptQuality = 1.0, .EnsureSuccessStatusCode = true, .EnsureMatchAcceptContentType = false
Task<SpecialResultClass> DemoApiMethod();