devdeer.Libraries.RestClient 4.1.5

devdeer.Libraries.RestClient

Disclaimer

If you want to use this package you should be aware of some principles and practices we at DEVDEER use. So be aware that this is not backed by a public repository. The purpose here is to give out customers easy access to our logic. Nevertheless you are welcome to use this lib if it provides any advantages.

Summary

This package provides a simple JSON REST client which is based on the HttpClient class. It is designed to be used in a .NET Core environment. The main purpose of this lib is to provide a simple way to call REST APIs and to handle the responses in a simple way. The lib is designed to be used in a dependency injection context.

Usage

Setup

In order to use the functionallity install the nuget package into your project. The you need to create a new type which inherits from JsonRestClient as follows:

public class MyRestClient : JsonRestClient
{
    public MyJsonClient(HttpClient httpClient) : base(httpClient)
    {
    }
}

The above example shows only the simples of 9 available constructor overloads. You need to pick only one of them in order to devide which DI (dependency injection) you want to use.

If you want to use your REST client conveniently you usually add it to your DI:

services.AddHttpClient<MyJsonClient>(
    (sp, client) =>
    {        
        var config = sp.GetRequiredService<IConfiguration>();        
        client.BaseAddress = new Uri($"https://{config["OtherApi:Hostname"]}");        
        client.DefaultRequestHeaders.Add("Accept", "application/json");
        // add more initialization if needed
    });

In the example shown you would have some value in your appsettings.json like:

{
    "OtherApi": {
        "Hostname": "other.api.com"
    }
}

Now lets say you have some component which needs to make JSON-REST-requests. You could do it like this:

public class MyComponent
{
    private MyJsonClient _client;

    public MyComponent(MyJsonClient client)
    {
        _client = client;
    }

    public async ValueTask<string> GetSomeDataAsync()
    {
        return await _client.GetAsync<string>("The/Relative/Endpoint");
    }

    public async ValueTask<SomeDataType> GetSomeDataAsync()
    {
        return await _client.GetAsync<SomeDataType>("Other/Relative/Endpoint");
    }
}

Passing in configuration options

There are other constructor overloads which allow you to pass the client configuration as well. Here is one example using the default options-injection:

public class MyRestClient : JsonRestClient
{
    public MyJsonClient(HttpClient httpClient, IOptions<JsonRestClientOptions> options) : base(httpClient, options)
    {
    }
}

In order for this to work you need to register the options in your startup-DI. This examples uses the helper method from devdeer.Libraries.Abstractions which is a transient Nuget package that you get with this one automatically:

using devdeer.Libraries.Abstractions.Extensions;

services.RegisterOption<JsonRestClientOptions>("MyRestClient");

and the appsettings.json:

{
    "OtherApi": {
        "Hostname": "other.api.com"
    },
    "MyRestClient": {
        "Resiliency": {
            "UseRetryPolicy": true,
            "RetryTimeoutBase": 1,
            "RetryCount": 5
        }
    }

This assumes that you only need 1 JsonRestClient in your project and so you can use the default JsonRestClientOptions.

If you however need to have several implementations of JsonRestClient in your project you need to do a little more work.

Lets say you want to have 2 clients like this:

public class MyRestClient1 : JsonRestClient
{
    public MyJsonClient(HttpClient httpClient, IOptions<JsonRestClientOptions> options) : base(httpClient, options)
    {
    }
}

public class MyRestClient2 : JsonRestClient
{
    public MyJsonClient(HttpClient httpClient, IOptions<JsonRestClientOptions> options) : base(httpClient, options)
    {
    }
}

This would work but both clients would then share the same JsonRestClientOptions instance. So lets create 2 new types:

public class JsonRestClientOptions1 : JsonRestClientOptions
{
}

public class JsonRestClientOptions2 : JsonRestClientOptions
{
}

Change your app settings now:

{
    "OtherApi": {
        "Hostname": "other.api.com"
    },
    "RestClients": {
        "1": {
            "Resiliency": {
                "UseRetryPolicy": true,
                "RetryTimeoutBase": 1,
                "RetryCount": 5
            }
        },
        "2": {            
        },
    }

The first client should use resiliency and the other should not. Now change your startup:

using devdeer.Libraries.Abstractions.Extensions;

services.RegisterOption<JsonRestClientOptions1>("RestClients:1");
services.RegisterOption<JsonRestClientOptions2>("RestClients:2");

Finally change the constructors of your types:

public class MyRestClient1 : JsonRestClient
{
    public MyJsonClient(HttpClient httpClient, IOptions<JsonRestClientOptions1> options) : base(httpClient, options)
    {
    }
}

public class MyRestClient2 : JsonRestClient
{
    public MyJsonClient(HttpClient httpClient, IOptions<JsonRestClientOptions2> options) : base(httpClient, options)
    {
    }
}

Calling methods

There are now several ways to use the client functionallity. The easiest way is to use wrapper functions like GetAsync<T> and PostAsync<T> as shown above.

One peculiar thing about our package are the *Oneway* functions which are there for you if just want to send a request to an endpoint and don't expect any result.

Also we provide a lot of overloads on the methods. In principal here are the ways to call our methods:

1. Provide relative path, HTTP method and an optional request-body represented as a string.
2. Provide relative path, HTTP method and an optional request-body represented as a pre-build custom HttpContent.
3. Provide the pre-build HttpRequestMessage directly.

This scheme applies to all wrappers and direct Invoke* methods.

On excemption are the PerformDynamicRequestAsync overloads. This can be used like this:

var genericTemp = await _client.PerformDynamicRequestAsync($"path", HttpMethod.Get);
if (result == null)
{
    // Whatever
}
 return result["jsonRoute"].GetProperty("someProp").GetDouble();

In other words: the dynamic methods will return a dynamic type and allow you to call an API without need to map the data to .NET types. Be aware that this has performance implications and should be avoided normally.

Resiliency

This package uses Polly and Microsoft.Extensions.Resilience to incorporate resiliency optionally.

A documentation of this is upcoming...

About DEVDEER

DEVDEER is a company from Magdeburg, Germany which is specialized in consulting, project management and development. We are very focussed on Microsoft Azure as a platform to run our products and solutions in the cloud. So all of our backend components usually runs in this environment and is developed using .NET. In the frontend area we are using react and a huge bunch of packages to build our UIs.

You can find us online:

• GitHub
• Twitter
• Youtube