Fonix.Extensions.ApiClient 1.0.1

Fonix APIs RestClient Extensions

This project extends functionality to the RestClient library by configuring the API endpoints from Fonix Telematics.

Note: version 0.2 introduces some breaking changes in how the APIs are registered. If you are migrating from 0.1.x please see migration notes.

Getting started

The first thing is to add the package reference

dotnet nuget add package Fonix.Extensions.ApiClient

Next, register the APIs RESTful client. Upon registering the required dependencies, an IApiRestClientBuilder instance is returned so that we can register the APIs we need.

IServiceCollection services = ... //

var builder = services.AddApiRestClient( options =>
{
    // if all requests are to use the same token, configure it here
    options.Token = "your-bearer-token";
} );

builder.AddCoreApi();

The extensions rely on the RestClient library, so to create a client for a specific library, we can use the IRestClientFactory extensions. For example:

public class MyClass
{
    private readonly IRestClient coreApi;
    private readonly IRestClient devicesApi;

    public MyClass( IRestClientFactory restClientFactory )
    {
        coreApi = restClientFactory.GetCoreApiClient();
        devicesApi = restClientFactory.GetDevicesApiClient();

        // if you prefer, you can also use the registered names
        coreApi = restClientFactory.CreateClient( ApiClientNames.Core )
    }
}

Extending endpoints

Something new that version 0.2 brought is the ability to extend the API with custom endpoints that aren't implemented in the library. There are a few different ways to do this, where the most direct one is to just add a custom endpoint with a name

IApiRestClientBuilder builder = ... //

builder.Add( "forms.fonixapis", "https://forms.fonixapis.com" );

A more complete approach would be to first extend the ApiOptions class.

internal class ExtendedApiOptions : ApiOptions
{
    public ExtendedApiOptions()
    {
        FormsUri = ExtendedApiClientEndpoints.Forms;
    }

    public string FormsUri { get; set; }

    public override void UseEnvironment( string name )
    {
        base.UseEnvironment( name );

        FormsUri = ExtendedApiClientEndpoints.Forms.Replace( ".fonixapis.", $".{name}.fonixapis." );
    }
}

We can then create an extension for the typed builder

internal static class ExtendedApiServiceExtensions
{
    public static IApiRestClientBuilder<ExtendedApiOptions> AddFormsApi( this IApiRestClientBuilder<ExtendedApiOptions> builder )
    {
        builder.Add( ExtendedApiClientNames.Forms, builder.Options.FormsUri );

        return ( builder );
    }
}

And finally, we use the typed builder instead of the default one, where we can use our extensions.

builder.Services.AddApiRestClient<ExtendedApiOptions>( options =>
{
    // ...
} )
.AddCoreApi()   // we can still add our Core API endpoint
.AddFormsApi(); // and our custom API endpoint

You can have a look at the examples folder in this repository for a complete walkthrough.

Migration notes

If you are upgrading from 0.1.x to 0.2, you need to keep in mind that the AddApiRestClient now returns a builder and that you need to add in the APIs you need.

So if you intend to use the Core API only, your code will change from this

IServiceCollection services = ... //

services.AddApiRestClient( options =>
{
    // if all requests are to use the same token, configure it here
    options.Token = "your-bearer-token";
} );

to this

services.AddApiRestClient( options =>
{
    // if all requests are to use the same token, configure it here
    options.Token = "your-bearer-token";
} )
.AddCoreApi();