CoreSharp.Http.FluentApi

HttpClient fluent request framework.

Features

• Strongly typed fluent syntax.
• Automatic JSON conversions using Text.Json or Json.NET.
• In-memory response caching for safe HTTP methods.
• Specific and more meaningful exceptions (HttpResponseException, TimeoutException).
• Use of Stream where applicable instead of eager converting entities to string. [Optimizes memory consumption]
• Use of HttpCompletionOption.ResponseHeadersRead by default to all requests. [Optimizes memory consumption and response times]

Installation

Install the package with Nuget.

dotnet add package CoreSharp.Http.FluentApi

Use cases

Table of Contents

• Start a request chain
• Headers
  • Accept
  • Authorization
• Query parameters
• Ignore error
• HttpCompletionOption
• Timeout
• Endpoint
• HTTP method
  • Safe methods
  • Unsafe methods
• Request body
  • JSON request body
  • XML request body
• Response deserialization
• Response caching

Start a request chain

HttpClient client = GetClient();
var request = client.Request();

Headers

var response = client
	.Request()
	.WithHeader("Cache-Control", "max-age=3600")
	.WithEndpoint("users")
	.Get()
	.SendAsync();

IDictionary<string, string> headers = GetHeaders();
var response = client
	.Request()
	.WithHeaders(headers)
	.WithEndpoint("users")
	.Get()
	.SendAsync();

Accept

// Accept: text/xml
var response = client
	.Request()
	.Accept("text/xml")
	.WithEndpoint("users")
	.Get()
	.SendAsync();

// Accept: application/json
var response = client
	.Request()
	.AcceptJson()
	.WithEndpoint("users")
	.Get()
	.SendAsync();

// Accept: application/xml
var response = client
	.Request()
	.AcceptXml()
	.WithEndpoint("users")
	.Get()
	.SendAsync();

Authorization

// Authorization: 0imfnc8mVLWwsAawjYr4Rx
var response = client
	.Request()
	.WithAuthorization("0imfnc8mVLWwsAawjYr4Rx")
	.WithEndpoint("users")
	.Get()
	.SendAsync();

// Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
var response = client
	.Request()
	.WithBearerToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9")
	.WithEndpoint("users")
	.Get()
	.SendAsync();

Query parameters

// GET > /users/?Id=1&Name="Makis"
var response = client
	.Request()
	.WithQuery("Id", 1)
	.WithQuery("Name","Makis")
	.WithEndpoint("users")
	.Get()
	.SendAsync();

// GET > /users/?Id=1&Name="Makis"
var response = client
	.Request()
	.WithQuery(new
	{
		Id = 1,
		Name = "Makis"
	})
	.WithEndpoint("users")
	.Get()
	.SendAsync();

// GET > /users/?Id=1&Name="Makis"
var queryParameters = new Dictionary<string, object>()
{
	{ "Id", 1 },
	{ "Name", "Makis" }
};
var response = client
	.Request()
	.WithQuery(queryParameters)
	.WithEndpoint("users")
	.Get()
	.SendAsync();

Ignore error

// Propagates / throws exception
var response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.SendAsync();

// Silence / does not throw exception
var response = client
	.Request()
	.IgnoreError()
	.WithEndpoint("users")
	.Get()
	.SendAsync();

HttpCompletionOption

var response = client
	.Request()
	.WithCompletionOption(HttpCompletionOption.ResponseContentRead)
	.WithEndpoint("users")
	.Get()
	.SendAsync();

Timeout

try
{
	var response = client
		.Request()
		.WithTimeout(TimeSpan.FromSeconds(15))
		.WithEndpoint("users")
		.Get()
		.SendAsync();
}
catch (TimeoutException timeoutException)
{
}

Endpoint

// GET /users/
var response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.SendAsync();

// GET /users/1/
int id = 1;
var response = client
	.Request()
	.WithEndpoint("users", id)
	.Get()
	.SendAsync();

// GET /users/1/
long id = 1;
var response = client
	.Request()
	.WithEndpoint("users", id)
	.Get()
	.SendAsync();

// GET /users/570ffbae-d1b8-4fad-9fef-5d058a283329/
Guid id = Guid.New();
var response = client
	.Request()
	.WithEndpoint("users", id)
	.Get()
	.SendAsync();

// GET /users/filter/new/
var response = client
	.Request()
	.WithEndpoint(new [] {"users", "filter", "new" })
	.Get()
	.SendAsync();

HTTP method

Safe methods

var response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.SendAsync();

var response = client
	.Request()
	.WithEndpoint("users")
	.Head()
	.SendAsync();

var response = client
	.Request()
	.WithEndpoint("users")
	.Options()
	.SendAsync();

var response = client
	.Request()
	.WithEndpoint("users")
	.Trace()
	.SendAsync();

Unsafe methods

var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.SendAsync();

var response = client
	.Request()
	.WithEndpoint("users")
	.Put()
	.SendAsync();

var response = client
	.Request()
	.WithEndpoint("users")
	.Patch()
	.SendAsync();

var response = client
	.Request()
	.WithEndpoint("users")
	.Delete()
	.SendAsync();

Request body

(supported only with unsafe methods)

HttpContent content = GetHttpContent();

var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.WithBody(content)
	.SendAsync();

string content = "data";
string mediaType = MediaTypeNames.Text.Plain;

var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.WithBody(content, mediaType)
	.SendAsync();

JSON request body

// Sets request Content-Type: application/json
// and HttpContent to StringContent.
var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.WithJsonBody(@"
	{
		""Name"": "Dave""
	}")
	.SendAsync();

// Serialize object to JSON stream,
// sets request Content-Type: application/json
// and HttpContent to StreamContent.
var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.WithJsonBody(new
	{
		Name = "Dave"
	})
	.SendAsync();

// Sets request Content-Type: application/json
// and HttpContent to StreamContent.
Stream stream = GetJsonStream(new
{
	Name = "Dave"
});

var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.WithJsonBody(stream)
	.SendAsync();

XML request body

// Serialize object to XML stream,
// sets request Content-Type: application/xml
// and HttpContent to StreamContent.
var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.WithXmlBody(new
	{
		Name = "Dave"
	})
	.SendAsync();

// Sets request Content-Type: application/xml
// and HttpContent to StreamContent.
Stream stream = GetXmlStream(new
{
	Name = "Dave"
});

var response = client
	.Request()
	.WithEndpoint("users")
	.Post()
	.WithXmlBody(stream)
	.SendAsync();

Response deserialization

HttpResponseMessage response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.SendAsync();

byte[] response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.ToBytes()
	.SendAsync();

Stream response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.ToStream()
	.SendAsync();

string response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.ToString()
	.SendAsync();

// Deserializes JSON with System.Text.Json by default
User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithJsonDeserialize<User>()
	.SendAsync();

// Deserialize with System.Text.Json
System.Text.Json.JsonSerializerOptions options = new();
User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithJsonDeserialize<User>(options)
	.SendAsync();

// Deserialize with Newtonsoft.Json
Newtonsoft.Json.JsonSerializerSettings settings = new();
User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithJsonDeserialize<User>(settings)
	.SendAsync();

User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithXmlDeserialize<User>()
	.SendAsync();

// Deserialize from string
static User Deserialize(String response) => ...;

User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithGenericDeserialize(Deserialize)
	.SendAsync();

// Deserialize from Stream
static User Deserialize(Stream response) => ...;

User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithGenericDeserialize(Deserialize)
	.SendAsync();

Response caching

(supported only with safe methods that return anything but HttpResponseMessage)

User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithJsonDeserialize<User>()
	.WithCache(TimeSpan.FromMinutes(15))
	.SendAsync();

static bool CacheInvalidationFactory() = ...;

User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithJsonDeserialize<User>()
	.WithCache(TimeSpan.FromMinutes(15))
	.WithCacheInvalidation(CacheInvalidationFactory)
	.SendAsync();

static Task<bool> CacheInvalidationFactory() = ...;

User response = client
	.Request()
	.WithEndpoint("users")
	.Get()
	.WithJsonDeserialize<User>()
	.WithCache(TimeSpan.FromMinutes(15))
	.WithCacheInvalidation(CacheInvalidationFactory)
	.SendAsync();