Restling 1.45.0-alpha2

Restling

A lightweight, powerful, and easy-to-use REST client library for .NET.

Overview

The goal of Restling is to provide a flexible yet easy-to-use REST client API. While it's true that there are plenty of REST client libraries out there, Restling wants to stand out by focusing on stability and offering support for uncommon features, such as cookie injection. It is also designed to integrate seamlessly into dependency injection-based projects as a transient service.

Features

• Lightweight and easy-to-use API.
• Built-in support for cookie injection.
• Designed for dependency injection (transient service).
• Full support for .NET's SocketsHttpHandler.
• Highly customizable via HttpClientContextBuilder.
• Extensible content codecs with JSON, XML, text, and binary/raw defaults.

Content codecs

Restling decodes responses by media type. Add custom codecs through HttpClientContextBuilder.AddCodec. Existing typed request payloads remain JSON unless RestRequest<T>.UseContentCodec is enabled explicitly. RFC 9457 Problem Details is available through ProblemDetailsJsonCodec, while CSV is supplied by the optional Restling.Csv package.

Ownership and disposal

Clients created with the default constructor or a builder own their generated context. Clients receiving an existing HttpClientContext borrow it by default. Use RestlingClientContextOwnership to select the behavior explicitly and HttpClientContextOwnership to control disposal of the underlying HttpClient and handler. DisposeContext remains a compatibility alias.

Multipart content

MultipartRequest sends form-data or any MIME multipart subtype with text, buffered binary, stream, arbitrary HttpContent, and codec-backed object parts. Buffered multipart responses deserialize to MultipartDocument, retaining ordered parts, duplicate names, headers, raw bytes, nested multipart content, related roots, and byte ranges. multipart/x-mixed-replace is available through a dedicated asynchronous streaming API.

Why the name "Restling"?

While chatting with a friend, the name came to mind as a pun combining "REST" and "Changeling," the Fae beings from Northern folk tales. Restling is a library that has taken on the form of a REST client—though its journey started as something entirely different.

Supported versions of DotNet

Restling supports both the latest .NET version and the latest LTS version, ensuring compatibility and stability for a wide range of projects.

LTS Version: .NET 10, 8 STS Version: .NET 9

Installation

You can use Visual Studio solution package management or use the following commands:

DotNet CLI

From a valid terminal:

dotnet add package Restling

NuGet Package Manager

Using Visual Studio powershell package manager:

Install-Package Restling

Basic usage:

The quickest way to use Restling is to allocate the client without parameters:

Example 1: Basic Usage

string uri;
RestlingClient restlingClient = new();
RestRequestResult restResponse;

// Call the uri resource without deserialization of the content
restResponse = await restlingClient.GetAsync(uri, cancellationToken)

Restling has a lot of customization options. You can use the HttpClientContextBuilder object to customize behavior of the client and http message handlers. In the following example, we will instantiate a HttpClientContext using the HttpClientContextBuilder instance, with the following characteristics:

• SocketsHttpHandler: the new .NET message handler.
• CookieContainer: a cookie container initialized using a cookie storage from the application database.
• ILogger<RestClientController>: a logger for the current executing object.
• A custom user agent.
• A default header app-version with a valid version string set.

This code will allow the Restling client to send and receive cookies when a method is executed, adding the app-version header and setting a new user-agent.

Explicit proxy

HttpClientContextBuilder builder = new();
builder.AddProxy("http://proxy.example.com:8080", allowAutoRedirect: false);
using RestlingClient client = new(builder);

AddProxy(string proxyUri, bool allowAutoRedirect) enables the proxy on a directly supplied SocketsHttpHandler or HttpClientHandler, or on the builder-created native handler. Cookie settings and ownership are preserved. allowAutoRedirect controls HTTP response redirects, not proxy bypass.

The address must be an absolute HTTP, HTTPS, SOCKS4, SOCKS4a, or SOCKS5 URI containing a host and optional port; embedded credentials, non-root paths, queries, and fragments are rejected. Native/platform transport support still applies. Configure proxy credentials through ConfigureHandler after AddProxy when needed.

Configure before the first request. AddProxy works before or after AddHandler and ConfigureHandler; later callback changes are retained by Build. A replacement native handler receives the last AddProxy selection. Custom/delegating handlers require explicit transport configuration and are rejected by this method. Existing custom builder implementations remain compatible through a default interface implementation that throws NotSupportedException.

Proxy selection applies to the whole context. Per-request overrides are not provided: use separate contexts/handlers for another proxy or direct connections (UseProxy = false). Existing defaults remain unchanged when AddProxy is not used.

Example 2: Advanced customization

HttpClientContextBuilder contextBuilder = new();
SocketsHttpHandler httpHandler = new();
CookieContainer cookieContainer = this.RetrieveCookieContainerFromDatabase();
RestlingClient restlingClient;
ILogger<RestClientController> logger = services.GetRequiredService<ILogger<RestClientController>>();
RestRequestResult<ResourceModel> restResponse;

httpHandler.CookieContainer = cookieContainer;

contextBuilder.AddHandler(httpHandler, diposeHandler: true);
contextBuilder.AddDefaultHeader("app-version", "1.0.0");
contextBuilder.AddUserAgent("AppThatUsesREST/1.0 (Windows NT 10.0; Win64; x64)");

restlingClient = new(contextBuilder, logger);

restResponse = await restlingClient.GetAsync<ResourceModel>(uri, cancellationToken);