Tiny.RestClient

<img src="https://raw.githubusercontent.com/jgiacomini/Tiny.RestClient/master/icon.png" width="200" height="200" />

Please visit the main site.

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.5+
• Xamarin iOS, Xamarin Android
• .Net Core
• UWP
• Windows Phone 8.1
• Windows 8.1

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 =