Tiny.RestClient
2.0.0-alpha003
Requires NuGet 3.0.3 or higher.
dotnet add package Tiny.RestClient --version 2.0.0-alpha003
NuGet\Install-Package Tiny.RestClient -Version 2.0.0-alpha003
<PackageReference Include="Tiny.RestClient" Version="2.0.0-alpha003" />
paket add Tiny.RestClient --version 2.0.0-alpha003
#r "nuget: Tiny.RestClient, 2.0.0-alpha003"
// Install Tiny.RestClient as a Cake Addin #addin nuget:?package=Tiny.RestClient&version=2.0.0-alpha003&prerelease // Install Tiny.RestClient as a Cake Tool #tool nuget:?package=Tiny.RestClient&version=2.0.0-alpha003&prerelease
<img src="https://raw.githubusercontent.com/jgiacomini/Tiny.RestClient/master/icon.png" width="200" height="200" />
Tiny.RestClient facilitates the dialog between your API and your application. It hides all the complexity of communication, deserialisation ...
Platform Support
The support of .NET Standard 1.1 to 2.0 allows you to use it with :
- .NET Framework 4.6.1
- .NET Standard 2.0
- .NET 6.0 or superior (Blazor, ASP.NET Core, ...)
Features
- Modern async http client for REST API.
- Support of verbs : GET, POST , PUT, DELETE, PATCH and custom http verbs
- Support of ETag
- Support of multi-part form data
- Support of cancellation token on each requests
- Support of : download file and Upload file
- Automatic XML and JSON serialization / deserialization
- Support of custom serialisation / deserialisation
- Support of camelCase, snakeCase kebabCase for json serialization
- Support of compression and decompression (gzip and deflate)
- Typed exceptions which are easier to interpret
- Define timeout globally or per request
- Timeout exception thrown if the request is in timeout (by default HttpClient sends OperationCancelledException, so we can't distinguish between user cancellation and timeout)
- Provide an easy way to log : all sending of request, failed to get response, and the time get response.
- Support of export requests to postman collection
- Support of display cURL requests in debug output
- Support of Basic Authentification
- Support of OAuth2 Authentification
Basic usage
Create the client
using Tiny.RestClient;
var client = new TinyRestClient(new HttpClient(), "http://MyAPI.com/api");
Headers
Default header for all requests
// Add default header for each calls
client.Settings.DefaultHeaders.Add("CustomHeader", "Header");
// Add Auth2.0 token
client.Settings.DefaultHeaders.AddBearer("token");
// Add default basic authentication header
client.Settings.DefaultHeaders.AddBasicAuthentication("username", "password");
Add header for current request
// Add header for this request only
client.GetRequest("City/All").
AddHeader("CustomHeader", "Header").
ExecuteAsync();
// Add header for this request only
client.GetRequest("City/All").
WithOAuthBearer("MYTOKEN").
ExecuteAsync();
// Add basic authentication for this request only
client.GetRequest("City/All").
WithBasicAuthentication("username", "password").
ExecuteAsync();
Calculate headers before send the requests
Before send requests to server we can add calculate dynamically the headers to add to resquest like below :
client.Settings.CalculateHeadersHandler = async () =>
{
var token = await GetACustomTokenAsync();
var headers = new Headers
{
{ "CustomToken", token },
};
return headers;
};
Read headers of response
await client.GetRequest("City/GetAll").
FillResponseHeaders(out headersOfResponse Headers).
ExecuteAsync();
foreach(var header in headersOfResponse)
{
Debug.WriteLine($"{current.Key}");
foreach (var item in current.Value)
{
Debug.WriteLine(item);
}
}
Basic GET http requests
var cities = client.GetRequest("City/All").ExecuteAsync<List<City>>();
// GET http://MyAPI.com/api/City/All an deserialize automaticaly the content
// Add a query parameter
var cities = client.
GetRequest("City").
AddQueryParameter("id", 2).
AddQueryParameter("country", "France").
ExecuteAsync<City>> ();
// GET http://MyAPI.com/api/City?id=2&country=France deserialize automaticaly the content
Basic POST http requests
// POST
var city = new City() { Name = "Paris" , Country = "France"};
// With content
var response = await client.PostRequest("City", city).
ExecuteAsync<bool>();
// POST http://MyAPI.com/api/City with city as content
// With form url encoded data
var response = await client.
PostRequest("City/Add").
AddFormParameter("country", "France").
AddFormParameter("name", "Paris").
ExecuteAsync<Response>();
// POST http://MyAPI.com/api/City/Add with from url encoded content
var fileInfo = new FileInfo("myTextFile.txt");
var response = await client.
PostRequest("City/Image/Add").
AddFileContent(fileInfo, "text/plain").
ExecuteAsync<Response>();
// POST text file at http://MyAPI.com/api/City/Add
Custom Http Verb requests
await client.
NewRequest(new System.Net.Http.HttpMethod("HEAD"), "City/All").
ExecuteAsync<List<City>>();
Define timeout
Define a global timeout for all client. (By default it's setted to 100 secondes)
client.Settings.DefaultTimeout = TimeSpan.FromSeconds(100);
Define the timeout for one request
request.WithTimeout(TimeSpan.FromSeconds(100));
Allow non http 2xx responses
Globaly
Allow any status codes :
client.Settings.HttpStatusCodeAllowed.AllowAnyStatus = true;
Allow only a range of http status codes :
client.Settings.HttpStatusCodeAllowed.Add(new HttpStatusRange(400, 420));
or
client.Settings.HttpStatusCodeAllowed.Add(new HttpStatusRange(System.Net.HttpStatusCode.BadRequest, System.Net.HttpStatusCode.BadGateway));
By request
Allow all status code :
request.AllowAllHttpStatusCode().ExecuteAsync();
Allow only a range of http status codes :
request.AllowRangeHttpStatusCode(400, 420).ExecuteAsync();
Allow only on stats code of http status codes :
request.AllowSpecificHttpStatusCode(409).ExecuteAsync();
Download file
string filePath = "c:\map.pdf";
FileInfo fileInfo = await client.
GetRequest("City/map.pdf").
DownloadFileAsync("c:\map.pdf");
// GET http://MyAPI.com/api/City/map.pdf
Get raw HttpResponseMessage
var response = await client.
PostRequest("City/Add").
AddFormParameter("country", "France").
AddFormParameter("name", "Paris").
ExecuteAsHttpResponseMessageAsync();
// POST http://MyAPI.com/api/City/Add with from url encoded content
Get raw string result
string response = await client.
GetRequest("City/All").
ExecuteAsStringAsync();
// GET http://MyAPI.com/api/City/All with from url encoded content
Multi-part form data
// With 2 json content
var city1 = new City() { Name = "Paris" , Country = "France"};
var city2 = new City() { Name = "Ajaccio" , Country = "France"};
var response = await client.NewRequest(HttpVerb.Post, "City").
await client.PostRequest("MultiPart/Test").
AsMultiPartFromDataRequest().
AddContent<City>(city1, "city1", "city1.json").
AddContent<City>(city2, "city2", "city2.json").
ExecuteAsync();
// With 2 byte array content
byte[] byteArray1 = ...
byte[] byteArray2 = ...
await client.PostRequest("MultiPart/Test").
AsMultiPartFromDataRequest().
AddByteArray(byteArray1, "request", "request2.bin").
AddByteArray(byteArray2, "request", "request2.bin")
ExecuteAsync();
// With 2 streams content
Stream1 stream1 = ...
Stream stream2 = ...
await client.PostRequest("MultiPart/Test").
AsMultiPartFromDataRequest().
AddStream(stream1, "request", "request2.bin").
AddStream(stream2, "request", "request2.bin")
ExecuteAsync();
// With 2 files content
var fileInfo1 = new FileInfo("myTextFile1.txt");
var fileInfo2 = new FileInfo("myTextFile2.txt");
var response = await client.
PostRequest("City/Image/Add").
AsMultiPartFromDataRequest().
AddFileContent(fileInfo1, "text/plain").
AddFileContent(fileInfo2, "text/plain").
ExecuteAsync<Response>();
// With 2 strings content
var response = await client.
PostRequest("City/Image/Text").
AsMultiPartFromDataRequest().
AddString("string1", "text/plain").
AddString("string2", "text/plain").
ExecuteAsync<Response>();
// With mixed content
await client.PostRequest("Files/Add").
AsMultiPartFromDataRequest().
AddContent<City>(city1, "city1", "city1.json").
AddByteArray(byteArray1, "request", "request2.bin").
AddStream(stream2, "request", "request2.bin")
AddString("string1", "text", "request.txt")
ExecuteAsync();
String, Streams and bytes array
You can use as content : strings, streams or byte arrays. If you use these methods no serializer will be used.
String
// Read string response
Stream stream = await client.
GetRequest("text").
ExecuteAsStringAsync();
// Post String as content
await client.PostRequest("poetry/text").
AddStringContent(stream).
ExecuteAsync();
Streams
// Read stream response
Stream stream = await client.
GetRequest("File").
ExecuteAsStreamAsync();
// Post Stream as content
await client.PostRequest("File/Add").
AddStreamContent(stream).
ExecuteAsync();
Byte array
// Read byte array response
byte[] byteArray = await client.
GetRequest("File").
ExecuteAsByteArrayAsync();
// Read byte array as content
await client.
PostRequest("File/Add").
AddByteArrayContent(byteArray).
ExecuteAsync();
Error handling
All requests can throw 5 exceptions :
- ConnectionException : thrown when the request can't reach the server
- HttpException : thrown when the server has invalid error code
- SerializeException : thrown when the serializer can't serialize the content
- DeserializeException : thrown when the deserializer can't deserialize the response
- TimeoutException : thrown when the request take too much time to be executed
Catch a specific error code
string cityName = "Paris";
try
{
var response = await client.
GetRequest("City").
AddQueryParameter("Name", cityName).
ExecuteAsync<City>();
}
catch (HttpException ex) when (ex.StatusCode == System.Net.HttpStatusCode.NotFound)
{
throw new CityNotFoundException(cityName);
}
catch (HttpException ex) when (ex.StatusCode == System.Net.HttpStatusCode.InternalServerError)
{
throw new ServerErrorException($"{ex.Message} {ex.ReasonPhrase}");
}
Enclapsulate HttpExceptions
We can setup a global handler to provide a logic to encapsulate HttpException automatically.
For example I can choose to translate all HttpException with StatusCode NotFound in a NotFoundCustomException.
client.Settings.EncapsulateHttpExceptionHandler = (ex) =>
{
if (ex.StatusCode == System.Net.HttpStatusCode.NotFound)
{
return new NotFoundCustomException();
}
return ex;
};
Now if I call an API wich respond with status code NotFound it will throw automaticaly my custom exception.
// Call an API wich throw NotFound error
await client.GetRequest("APIWhichNotExists").ExecuteAsync();
ETag
The lib supports the Entity tag but it's not enabled by default.
Define an ETagContainer globally
An implementation of IETagContainer is provided. It stores all data in multiples files.
To enable it :
client.Settings.ETagContainer = new ETagFileContainer(@"C:\ETagFolder");
Define an ETagContainer for one request
You can also define the ETagContainer only on specific request.
request.WithETagContainer(eTagContainer);
Formatters
By default :
- the Json is used as default Formatter.
- Xml Formatter is added in Formatters
Each formatter has a list of supported media types. It allows TinyRestClient to detect which formatter will be used. If no formatter is found it uses the default formatter.
Add a new formatter
Add a new custom formatter as default formatter.
bool isDefaultFormatter = true;
var customFormatter = new CustomFormatter();
client.Settings.Formatters.Add(customFormatter, isDefaultFormatter);
Remove a formatter
var lastFormatter = client.Settings.Formatters.First(f => f is XmlSerializer);
client.Settings.Formatters.Remove(lastFormatter);
Json custom formatting
You can enable 4 types of formatting on JsonFormatter :
- PascalCase (PropertyName ⇒ PropertyName)
- CamelCase (PropertyName ⇒ propertyName) (default)
- SnakeCase (PropertyName ⇒ property_name)
- KebabCase (aslo known as SpinalCase) (PropertyName ⇒ property-name).
// Enable CamelCase
client.Settings.Formatters.OfType<JsonFormatter>().First().UseCamelCase();
By default the JSONFormatter use camelCase.
// Enable PascalCase
client.Settings.Formatters.OfType<JsonFormatter>().First().UsePascalCase();
// Enable KebabCase
client.Settings.Formatters.OfType<JsonFormatter>().First().UseKebabCase();
// Enable SnakeCase
client.Settings.Formatters.OfType<JsonFormatter>().First().UseSkakeCase();
Define a specific serialize for one request
IFormatter serializer = new XmlFormatter();
var response = await client.
PostRequest("City", city, serializer).
ExecuteAsync();
Define a specific deserializer for one request
IFormatter deserializer = new XmlFormatter();
var response = await client.
GetRequest("City").
AddQueryParameter("Name", cityName).
ExecuteAsync<City>(deserializer);
Custom formatter
You can create your own serializer/deserializer by implementing IFormatter
For example the implementation of XmlFormatter is really simple :
public class XmlFormatter : IFormatter
{
public string DefaultMediaType => "application/xml";
public IEnumerable<string> SupportedMediaTypes
{
get
{
yield return "application/xml";
yield return "text/xml";
}
}
public ValueTask<T> DeserializeAsync<T>(Stream stream, Encoding encoding, CancellationToken cancellationToken)
{
using (var reader = new StreamReader(stream, encoding))
{
var serializer = new XmlSerializer(typeof(T));
return ValueTask.FromResult((T)serializer.Deserialize(reader));
}
}
public Task<string> SerializeAsync<T>(T data, Encoding encoding, CancellationToken cancellationToken)
{
if (data == default)
{
return null;
}
var serializer = new XmlSerializer(data.GetType());
using (var stringWriter = new DynamicEncodingStringWriter(encoding))
{
serializer.Serialize(stringWriter, data);
return Task.FromResult(stringWriter.ToString());
}
}
}
Listeners
You can easily add a listener to listen all the sent requests / responses received and all exceptions.
Two listeners are provided by the lib :
- A debug listener : which logs all requests in debug console
- A postman listener : which allows you to export all your requests as a postman collection
Debug Listener
To add a Debug listener you have to call AddDebug on Listeners property
client.Settings.Listeners.AddDebug();
cURL Listener
To add a cURL listener you have to call AddCurl on Listeners property
client.Settings.Listeners.AddCurl();
It produce this type of output in debug window for each ExecuteAsync called :
curl -X POST "http://localhost:4242/api/PostTest/complex"-H "Accept: application/json" -H "Content-Type: application/json" -d "{\"Id\":42,\"Data\":\"DATA\"}"
Postman Listener
To add a postman listener you have to call AddPostman on Listeners property
PostmanListerner postmanListener = client.Settings.Listeners.AddPostman("nameOfCollection");
When you want to save the postman collection you have to call SaveAsync
await postmanListener.SaveAsync(new FileInfo("postmanCollection.json");
If you only want the Json of collection you can call the method GetCollectionJson
listener.GetCollectionJson();
Custom Listener
You can also create you own listener by implementing IListener.
IListener myCustomListerner = ..
client.Settings.Listeners.Add(myCustomListerner);
Compression and Decompression
By default, the client supports the decompression of Gzip and deflate.
If the server respond with the header ContentEncoding "gzip" or "deflate" the client will decompress it automaticly.
Compression
For each request which posts a content you can specified the compression algorithm like below
var response = await client.
PostRequest("Gzip/complex", postRequest, compression: client.Settings.Compressions["gzip"]).
ExecuteAsync<Response>();
Warning : the server must be able to decompress your content.
Decompression
Even if it's supported the client didn't send Accept-Encoding header automaticaly.
You can add it for gzip all request like below :
var compression = client.Settings.Compressions["gzip"];
compression.AddAcceptEncodingHeader = true;
You can add it for deflate all requests like below :
var compression = client.Settings.Compressions["deflate"];
compression.AddAcceptEncodingHeader = true;
If the server can compress response, it will respond with compressed content.
Custom ICompression
You can add your own compression / decompression algorithm :
client.Settings.Add(new CustomCompression());
Your class must implement the interface ICompression.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- System.Text.Json (>= 8.0.5)
-
.NETStandard 2.1
- System.Text.Json (>= 8.0.5)
-
net8.0
- No dependencies.
NuGet packages (4)
Showing the top 4 NuGet packages that depend on Tiny.RestClient:
Package | Downloads |
---|---|
Cardinal.ClickSign
Biblioteca de acesso à api do serviço de assinatura de documentos online ClickSign baseada em .Net Standard 2.0. |
|
FrappeRestClient.Net
.Net REST client for Frappe Framework |
|
Cardinal.AspNetCore.Identity
Biblioteca de autenticação e autorização Cardinal .NET Core API. |
|
Coder.WebHttpClient
提供简易的HttpClient访问方式 |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
2.0.0-alpha003 | 583 | 10/17/2024 |
2.0.0-alpha002 | 57 | 10/17/2024 |
2.0.0-alpha001 | 401 | 9/6/2024 |
1.7.1 | 115,851 | 5/29/2020 |
1.7.0 | 19,567 | 11/1/2019 |
1.6.6 | 2,283 | 10/16/2019 |
1.6.5 | 1,988 | 10/16/2019 |
1.6.4 | 13,633 | 8/13/2019 |
1.6.3 | 2,928 | 5/21/2019 |
1.6.2 | 2,034 | 5/4/2019 |
1.6.1 | 43,438 | 1/21/2019 |
1.6.0 | 4,240 | 10/27/2018 |
1.5.5 | 1,624 | 10/18/2018 |
1.5.4 | 1,523 | 10/18/2018 |
1.5.3 | 1,529 | 10/1/2018 |
1.5.2 | 1,500 | 9/30/2018 |
1.5.1 | 1,467 | 9/26/2018 |
1.5.1-alpha001 | 1,310 | 9/25/2018 |
1.5.0 | 1,465 | 9/23/2018 |
1.4.2 | 1,557 | 9/17/2018 |
1.4.1 | 1,483 | 9/16/2018 |
1.4.0 | 1,507 | 9/16/2018 |
1.3.5 | 2,215 | 9/11/2018 |
1.3.4 | 1,469 | 9/10/2018 |
1.3.3 | 1,481 | 9/10/2018 |
1.3.3-alpha0001 | 1,353 | 9/10/2018 |
1.3.2 | 1,498 | 9/9/2018 |
1.3.1 | 1,489 | 9/9/2018 |
1.3.0 | 1,585 | 9/9/2018 |
See release notes at https://github.com/jgiacomini/Tiny.RestClient/blob/master/RELEASE-NOTES.md