Dosaic.Extensions.RestEase 1.2.9

Dosaic.Extensions.RestEase

Dosaic.Extensions.RestEase is an extension library that simplifies typed HTTP API client creation using RestEase. It provides a static RestClientFactory with built-in OAuth2 authentication and Polly-based retry policies out of the box.

Installation

dotnet add package Dosaic.Extensions.RestEase

or add as a package reference to your .csproj:

<PackageReference Include="Dosaic.Extensions.RestEase" Version="" />

Features

• Typed HTTP clients — define an interface with RestEase attributes and get a fully functional client
• OAuth2 authentication — automatic token acquisition (password, client credentials, authorization code grants)
• Automatic token refresh — transparently refreshes the access token using the refresh token before it expires
• Polly retry policy — configurable retry; defaults to 2 retries (3 total attempts) on HTTP 5xx responses
• Custom JSON serialisation — defaults to Newtonsoft.Json with StringEnumConverter; fully replaceable
• All overloads composable — use only the features you need; everything beyond baseAddress is optional

Configuration

AuthenticationConfig can be populated from appsettings.json / appsettings.yaml via the standard IConfiguration binding:

{
  "MyApi": {
    "Auth": {
      "Enabled": true,
      "BaseUrl": "https://auth.example.com",
      "TokenUrlPath": "realms/myrealm/protocol/openid-connect/token",
      "GrantType": "ClientCredentials",
      "ClientId": "my-client",
      "ClientSecret": "s3cr3t"
    }
  }
}

MyApi:
  Auth:
    Enabled: true
    BaseUrl: https://auth.example.com
    TokenUrlPath: realms/myrealm/protocol/openid-connect/token
    GrantType: ClientCredentials
    ClientId: my-client
    ClientSecret: s3cr3t

Bind to AuthenticationConfig in your plugin or startup code:

var authConfig = configuration.GetSection("MyApi:Auth").Get<AuthenticationConfig>();

Usage

Basic Client

Define an interface using RestEase attributes:

using RestEase;

public interface IUserApi
{
    [Get("users/{userId}")]
    Task<User> GetUserAsync([Path] Guid userId, CancellationToken cancellationToken);

    [Post("users")]
    Task<User> CreateUserAsync([Body] User user, CancellationToken cancellationToken);

    [Put("users/{userId}")]
    Task UpdateUserAsync([Path] Guid userId, [Body] User user, CancellationToken cancellationToken);

    [Delete("users/{userId}")]
    Task DeleteUserAsync([Path] Guid userId, CancellationToken cancellationToken);
}

Create a client instance with just a base address:

using Dosaic.Extensions.RestEase;

IUserApi api = RestClientFactory.Create<IUserApi>("https://api.example.com");
var user = await api.GetUserAsync(userId, CancellationToken.None);

Authentication

Pass an AuthenticationConfig to enable OAuth2. The AuthHandler acquires a token on the first request and automatically refreshes it when the access token expires (as long as the refresh token is still valid):

using Dosaic.Extensions.RestEase;
using Dosaic.Extensions.RestEase.Authentication;

var authConfig = new AuthenticationConfig
{
    Enabled = true,
    BaseUrl = "https://auth.example.com",
    TokenUrlPath = "realms/myrealm/protocol/openid-connect/token",
    GrantType = GrantType.ClientCredentials,
    ClientId = "my-client",
    ClientSecret = "s3cr3t"
};

IUserApi api = RestClientFactory.Create<IUserApi>("https://api.example.com", authConfig);

Supported Grant Types

// Password grant
var authConfig = new AuthenticationConfig
{
    Enabled = true,
    BaseUrl = "https://auth.example.com",
    TokenUrlPath = "oauth/token",
    GrantType = GrantType.Password,
    ClientId = "my-client",
    Username = "alice",
    Password = "s3cr3t"
};

Custom Retry Policy

Supply any IAsyncPolicy<HttpResponseMessage> from Polly:

using Dosaic.Extensions.RestEase;
using Polly;
using System.Net.Http;

var retryPolicy = Policy
    .HandleResult<HttpResponseMessage>(r => r.StatusCode == System.Net.HttpStatusCode.Conflict)
    .RetryAsync(2);

IUserApi api = RestClientFactory.Create<IUserApi>("https://api.example.com", retryPolicy);

Advanced — All Options

using Dosaic.Extensions.RestEase;
using Dosaic.Extensions.RestEase.Authentication;
using Newtonsoft.Json;
using Polly;

var authConfig = new AuthenticationConfig
{
    Enabled = true,
    BaseUrl = "https://auth.example.com",
    TokenUrlPath = "oauth/token",
    GrantType = GrantType.ClientCredentials,
    ClientId = "my-client",
    ClientSecret = "s3cr3t"
};

var retryPolicy = Policy
    .HandleResult<HttpResponseMessage>(r => (int)r.StatusCode >= 500)
    .RetryAsync(3);

var jsonSettings = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore
};

IUserApi api = RestClientFactory.Create<IUserApi>(
    "https://api.example.com",
    authConfig,
    retryPolicy,
    jsonSettings
);

API Reference

RestClientFactory

AuthenticationConfig

Default Behaviour

• JSON — Newtonsoft.Json with StringEnumConverter (enums serialised as strings)
• Retry — RetryAsync(2) on HTTP 5xx (500–599), meaning 3 total attempts
• Auth — disabled by default; no Authorization header is added unless AuthenticationConfig.Enabled = true
• Token refresh — when the access token is expired but the refresh token is still valid, the library uses the refresh_token grant automatically; when both are expired a new token is acquired