ChilliSource.Mobile.Api

This project is part of the ChilliSource framework developed by BlueChilli.

Summary

ChilliSource.Mobile.Api is a wrapper around Refit, enhacing and simplifying REST API communication.

Usage

API Contract

Create a Refit interface defining the API endpoints you would like to access:

public interface IExampleApi
{    
    [Post("/login")]
    Task<AuthenticatedUser> Login([Body] LoginRequest request);

    [Post("/logout")]
    Task<MessageResponse> Logout();
}

The classes LoginRequest, AuthenticatedUser, and MessageResponse represent the Json entities that your API returns or expects to receive.

API Header Fields

Provide the header fields that your API requires for authorization and tracking by creating an ApiToken:

var info = new EnvironmentInformation(environment, appId, appVersion, 
    timeZone, platform, appName, deviceName);
var token = new ApiToken(apiKey, info, null);

Optionally you can also specify a user key in the token, either in the constructor or by setting the token's UserKey property.

API Configuration

Create the ApiConfiguration using your API URL and the API token:

var config = new ApiConfiguration(apiUrl, () =>
{
    return new ApiAuthenticationHandler(() =>
    {
        return Task.FromResult(token);
    }, new NoNetworkHandler(CrossConnectivity.Current, new NativeMessageHandler
    {
        AutomaticDecompression = System.Net.DecompressionMethods.GZip
    }));
});

The ApiConfiguration class can take multiple HTTP handlers to deal with different types of HTTP events, such as an authentication request or a network connectivity issue.

The NoNetworkHandler class relies on the Connectivity Plugin.

Additionally you can also handle the scenarios of the session expiring or the network connection becoming unavailable:

config.OnSessionExpired = result =>
        {
            Console.WriteLine("Session has expired");            
        };

config.OnNoNetworkConnectivity = result =>
        {
            Console.WriteLine("Network connection unavailable");            
        };

API Manager

Create a new ApiManager using the configuration and Refit interface you created in the steps above:

var manager = new ApiManager<IExampleApi>(config);

Invoking API Endpoints

Now you can invoke your API's endpoints in a type-safe manner through the ApiManager instance:

var loginResult = await manager.Client
                .Login(new LoginRequest("username", "password"))
                .WaitForResponse(continueOnCapturedContext: true);

if (loginResult.IsFailure)
{
    Console.WriteLine(loginResult.StatusCode);
}
else
{
    var authenticatedUser = loginResult.Result;
    Console.WriteLine("Welcome " + authenticatedUser.Name);
}

You can also use a fluent syntax to check for the various result states:

var loginResult = await manager.Client
                .Login(new LoginRequest("username", "password"))
                .WaitForResponse(continueOnCapturedContext: true)
                .OnFailure((result) =>
                    {
                        Console.WriteLine(result.StatusCode);
                    })
                .OnCancelled(() =>
                    {
                        Console.WriteLine("Login cancelled");
                    })
                .OnSuccess((result) =>
                    {
                        var authenticatedUser = result.Result;
                        Console.WriteLine("Welcome: " + authenticatedUser.Name);
                        return result;
                    }); 

Or asynchronously like this:

var loginResult = await manager.Client
                .Login(new LoginRequest("username", "password"))
                .WaitForResponse(continueOnCapturedContext: true)
                .OnFailure(async result =>
                    {
                        await Task.Run(() =>
                        {
                            Console.WriteLine(result.StatusCode);
                        });  
                    })
                .OnCancelled(async result =>
                    {
                        await Task.Run(() =>
                        {
                            Console.WriteLine("Login cancelled");
                        });
                    })
                .OnSuccess(async result =>
                    {
                        await Task.Run(() =>
                        {
                            var authenticatedUser = result.Result;
                            Console.WriteLine("Welcome: " + authenticatedUser.Name);
                        });
                    }); 

Handling error statues for each request

In addition to the generic event handlers defined in the API Configuration above, you can also define handlers for each request:

    var handler = new ApiExceptionHandlerConfig(
                    onNoNetworkConnectivity: result =>
                        {
                            hasNetwork = false;
                        },
                    onSessionExpired: result =>
                        {
                            hasSessionExpired = true;
                        });

    var result = await manager.Client
            .Login(new LoginRequest("username", "password"))
            .WaitForResponse(handler, continueOnCapturedContext: true)
            .OnFailure((failureResult) =>
                {
                    Console.WriteLine(failureResult.StatusCode);
                });

Installation

The library is available via NuGet here.

Releases

See the releases.

Contribution

Please see the Contribution Guide.

License

ChilliSource.Mobile is licensed under the MIT license.

Feedback and Contact

For questions or feedback, please contact [email protected].