DalSoft.RestClient 5.0.0

DalSoft .NET REST Client for all platforms

If you find this repo / package useful all I ask is you please star it ⭐

Do you or the company you work for benefit from the tools I build? <br /> If so please consider Becoming a Sponsor it would be greatly appreciated ❤️

For everything you need to know, please head over to https://restclient.dalsoft.io

👉 New Static Typing and Resource Expressions in 4.0

Just some of the things you can do with DalSoft.RestClient

• Easliy Create Fluent SDK's
• Unit Testing
• Post Json
• Post Forms
• Post Files
• Retry Requests
• Twitter SDK
• Raw HTTP
• Passthrough HttpClient
• Authorization

Supported Platforms

RestClient targets .NET Standard 2.0 therefore supports Windows, Linux, Mac and Xamarin (iOS, Android and UWP).

.NET 5.0 and .NET 6.0 supported All versions of .NET Core supported All versions of legacy .NET Framework > 4.6.1 supported

Getting Started

Install via .NET CLI

> dotnet add package DalSoft.RestClient

Install via NuGet

PM> Install-Package DalSoft.RestClient

Example calling a REST API

You start by new'ing up the RestClient and passing in the base uri for your RESTful API.

For example if your wanted to perform a GET on https://jsonplaceholder.typicode.com/users/1 you would do the following:

Static Typed Rest Client

For the Static typed Rest Client just pass a string representing the resource you want access to the Resource method, and then call the HTTP method you want to use.

var client = new RestClient("https://jsonplaceholder.typicode.com");

User user = await client.Resource("users/1").Get();
   
Console.WriteLine(user.Name);

Dynamicaly Typed Rest Client

For the Dynamicaly typed Rest Client chain members that would make up the resource you want to access - ending with the HTTP method you want to use.

dynamic client = new RestClient("https://jsonplaceholder.typicode.com");

var user = await client.Users(1).Get();
   
Console.WriteLine(user.name);

Note all HTTP methods are async

Recent Releases

• Version 5.0 System.Text.Json by default - see breaking changes below
• Version 4.0 Static Typing and Resource Expressions
• Version 3.3.0 IHttpClientFactory Goodness
• Version 3.0 Pipeline Awesomeness

About

RestClient is a very lightweight wrapper around System.Net.HttpClient that uses the dynamic features of .NET 4 to provide a fluent way of accessing RESTFul API's, making it trivial to create REST requests using a lot less code.

Originally created to remove the boilerplate code involved in making REST requests using code that is testable. I know there are a couple of REST clients out there but I wanted the syntax to look a particular way with minimal fuss.

RestClient is biased towards posting and returning JSON - if you don't provide Accept and Content-Type headers then they are set to application/json by default See Working with non JSON content.

Version 5.0 Breaking Changes

From version 5.0 RestClient uses System.Text.Json to serialize requests and deserialize responses - with stock System.Text.Json behaviour, so [JsonPropertyName] attributes are honoured and property matching is case sensitive. The only leniency added on top of the stock defaults is that trailing commas and comments are accepted when reading, because real world systems are less than perfect.

To customise serialization pass your JsonSerializerOptions:

var config = new Config().SetJsonSerializerOptions(new JsonSerializerOptions(JsonSerializerDefaults.Web)); 

If you need the legacy Json.NET behaviour ([JsonProperty] attributes, JsonSerializerSettings etc.) opt in to the fallback - this restores the 4.x behaviour exactly:

var config = new Config().UseNewtonsoftJson(); // optionally takes your JsonSerializerSettings

SetJsonSerializerSettings and Config.JsonSerializerSettings have been removed - use UseNewtonsoftJson(jsonSerializerSettings) instead. Note that failed typed casts now throw System.Text.Json.JsonException unless you opt in to Json.NET.

Performance

Near-native performance - typed requests allocate the same as using HttpClient and System.Text.Json by hand, and several times leaner than RestSharp.

Version 5.0 had a performance pass guided by BenchmarkDotNet - requests and responses are serialized straight to and from utf-8 bytes skipping intermediate strings, the JSON DOM is only built if you use dynamic access (typed casts skip it entirely), and arrays are wrapped lazily.

Before and after the performance pass, 10,000 item JSON payload, in process (no network), .NET 8:

Measured against using HttpClient and System.Text.Json by hand, POST request bodies and typed responses now allocate about the same (1.0x), down from 3.0x and 3.5x respectively.

Real world comparison

A real GET request to the GitHub API (https://api.github.com/repos/DalSoft/DalSoft.RestClient) deserialized to a typed model, compared to native HttpClient and other popular REST clients, .NET 8:

Time over a real network is dominated by latency so every client lands within noise of native HttpClient - don't read the time column as a ranking, the differences (including where a client appears faster than native HttpClient) are statistical noise. The allocations column is what shows the overhead each library adds per request. DalSoft.RestClient stays close to native and the lightweight clients while giving you a full dynamic API, and allocates about 6x less than RestSharp.

* RestClient.Net 7 doesn't deserialize for you - you supply your own System.Text.Json delegate, so its numbers exclude the library-side JSON handling every other row includes.

To run the benchmarks yourself: dotnet run -c Release in the DalSoft.RestClient.Benchmarks project. The real world benchmark makes around 50 requests - GitHub allows 60 unauthenticated requests an hour, set the GITHUB_TOKEN environment variable to raise the limit.

Standing on the Shoulders of Giants

DalSoft.RestClient is built using the following great open source projects:

• System.Text.Json
• Json.NET
• System.Net.Http

DalSoft.RestClient is inspired by and gives credit to:

• Simple.Data
• This Stack Overflow question