RESTSchemaRetry 4.0.2

RESTSchemaRetry

RESTSchemaRetry is a .NET library that implements a simple Schema-Retry pattern in REST API context to enhance application resilience. A Schema-Retry handles transient failures when attempting to connect to a service or network resource by transparently retrying failed operations.

How it works

RESTSchemaRetry implements a straightforward retry mechanism with a delay, managing communication timeouts or service errors transparently to the application. The retry mechanism checks the HTTP response code to determine whether the error is transient or not.

Transient error recovery

Below is the list of potentially transient errors handled by RESTSchemaRetry:

• TooManyRequests
• InternalServerError
• BadGateway
• ServiceUnavailable
• GatewayTimeout
• InsufficientStorage
• RequestTimeout
• HttpVersionNotSupported
• NetworkAuthenticationRequired

Supported Backoff Types

• Constant Backoff: The delay between retries is constant and does not change. This is a simple approach where each retry attempt waits for a fixed amount of time, defined by a RetryDelay parameter.

• Linear Backoff: The delay between retries increases linearly. Each retry attempt waits longer than the previous one by a fixed increment. The delay is calculated as RetryDelay * (retry + 1).

• Exponential Backoff: The delay between retries grows exponentially. The delay is calculated using a power of 2, multiplied by the base RetryDelay. This approach is useful to quickly back off from a failing operation, reducing server load. Formula: RetryDelay * (2 ^ retry).

• Exponential Backoff with Jitter: Similar to exponential backoff, but with added randomness ("jitter") to the delay to avoid synchronized retries from multiple clients, which can cause spikes in traffic. The delay is calculated as RetryDelay * (2 ^ retry) * random_factor, where random_factor is a random value between 0 and 1.

• Fibonacci Backoff: The delay between retries follows the Fibonacci sequence. This provides a middle ground between linear and exponential backoff, growing less aggressively than exponential. The delay is calculated as RetryDelay * Fibonacci(retry).

• Randomized Backoff: The delay is randomly chosen between a minimum and a maximum range, usually defined as a multiple of RetryDelay. This helps to distribute retries more evenly over time, avoiding bursts of traffic. The delay is calculated randomly within a range, e.g., [RetryDelay, RetryDelay * 2].

• Exponential Full Jitter Backoff: This strategy provides exponential backoff with full jitter. It’s especially effective for reducing collision and spreading retries over time.delay = random(0, RetryDelay * 2^retry) (capped to a max delay).

Backoff Strategies Comparison

How to use it

To use the RESTSchemaRetry library, just create a RetryClient specifying the base URL and the resource. There are multiple constructor to specify the REST API parameters.

var retryClient = new RetryClient("https://example.com/","your-rest-resourse");

The client supports both default Bearer token authentication and the ability to inject custom headers. You can provide either an authentication token or a dictionary of custom headers as shown below:

var retryClient = new RetryClient(
    baseUrl: "https://example.com/",
    resource: "your-rest-resource",
    authToken: "your-bearer-token" // optional
);

Or with custom headers:

var customHeaders = new Dictionary<string, string>
{
    { "Authorization", "Bearer your-custom-token" },
    { "X-Custom-Header", "value" }
};

var retryClient = new RetryClient(
    baseUrl: "https://example.com/",
    resource: "your-rest-resource",
    defaultHeaders: customHeaders
);

At this point the REST API requests can be performed. For example, below how to execute a POST request:

var response = retryClient.Post<TRequest, TResponse>(objectToPost);

Alternatively, you can register the library via dependency injection as follows:

builder.Services.AddRetryClient("https://your-base-url.com", "your-rest-resourse");

RESTSchemaRetry uses the RestSharp library to execute the web requests.

NuGet Package

The library is available on NuGet packetmanager. https://www.nuget.org/packages/RESTSchemaRetry/

RestSharp Reference

RESTSchemaRetry uses the RestSharp library, which is distributed under Apache 2.0 license.

• Official Project
• License

Contributing

Thank you for considering to help out with the source code! If you'd like to contribute, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base.

• Setting up Git
• Fork the repository
• Open an issue if you encounter a bug or have a suggestion for improvements/features

Licensee

RESTSchemaRetry source code is available under MIT License, see license in the source.

Contact

Please contact at francesco.delre[at]protonmail.com for any details.