Skip to main content

.NET wrapper

The .NET wrapper has been made to simplify the process of interacting with the API in a .NET application.

The wrapper is available on Nuget.

Examples of how to use the wrapper are available on Github.

Each function in the wrapper maps to an endpoint on the API.

Instantiation and authentication​

To make requests from the API, the wrapper must be authenticated. This can be done using a normal API Key or OAuth.

API Key​

The API key can be passed to the wrapper when it is initialized. When initializing the ApiClient instance an AuthenticationManager instance is required. For example:

var authManager = new AuthenticationManager(eAuthenticationMode.ApiKey, "API KEY HERE");
var apiClient = new ApiClient(authManager);

The AuthenticationManager is in the HHDev.DataManagement.Client.Authentication namespace.

OAuth​

To use the OAuth protocol for authentication. Create a SimpleAuthenticationSettings instance with the OAuth AuthenticationMode. Then assign this to both the OAuthAuthenticationManager and authentication manager supplied when instantiating the ApiClient like so:

// The same AuthenticationSettings instance must be shared between OAuthAuthenticationManager and the AuthenticationManager given to the ApiClient instance.
var sharedAuthSettings = new SimpleAuthenticationSettings
{
    AuthenticationMode = eAuthenticationMode.OAuth
};
OAuthAuthenticationManager.AuthenticationSettings = sharedAuthSettings;
var apiClient = new ApiClient(new AuthenticationManager(sharedAuthSettings));

When the application is run, the default system browser will open and ask the user to login with their username and password (just as when logging into hh-dev.com).

All relevant authentication classes are in the HHDev.DataManagement.Client.Authentication namespace.

Concept​

The general concept of the wrapper follows the same concept as the API, providing functions to get lists of items as well as single items, create and delete items. One of the advantages of the wrapper is that it handles the multi-step process of uploading attached files.

All functions in the API wrapper have an account ID argument which is used in the AccountId header

ApiGetResult<T>​

The generic class ApiGetResult<T> is returned from all Add and Get functions. T will be a different type depending on the endpoint. For the setups endpoint T will be ApiSetupModel.

The ApiGetResult<T> has the following properties:

  • bool Success: will be false if the request failed - in which case more information can be found in the Message and StatusCode properties
  • string Message: if the request failed this property will provide more information on the reason for the failure
  • HttpStatusCode StatusCode: the status code of the request
  • T ReturnValue: if the request is successful the created object will be available in this property, as it would be if a GET request was made. The item will be populated as if parametersToInclude has a value of *

Add functions​

To add a new item using the wrapper use the AddXX functions. Some IDs will be required as arguments to express where the new item should be created. For example when creating a setup, the eventId and carId will be required. A CreateModel instance is also required which has the properties explained in the creating items section of the API documentation.

For example:

var addSetupResult = await _apiClient.AddSetup(accountId, eventId, carId, new CreateModel()
{
    CopyFromLast = true,
});

The add functions return a ApiGetResult<T>.

Get functions​

To get an item using the wrapper there are multiple options, as with the API. A single item can be retrieved by ID, or a list of items can be retrieved by passing in the appropriate parent IDs. For example when getting a list of setups, the eventId and carId will be required. An ApiGetOptions instance is also required which contains the parametersToInclude information.

The get functions return a ApiGetResult<T>. The T will be either an item or a List of items depending on the function called.

For example:

var getSetupResult = await _apiClient.GetSetupById(accountId, setupId, new ApiGetOptions()
{
    ParametersToInclude = new List<string>()
    {
        "*",
    }
});

This will return a ApiGetResult<ApiSetupModel>.

var getSetupResult = await _apiClient.GetAllSetupsForEventCar(accountId, eventId, carId, new ApiGetOptions()
{
    ParametersToInclude = new List<string>()
    {
        "*",
    }
});

This will return a ApiGetResult<List<ApiSetupModel>>.

Update functions​

To update an item using the wrapper use the UpdateXX functions. The ID of the item to be updated will need to be provided as an argument. An UpdateModel instance is also required which contains the parametersToInclude information.

The update functions return a bool that indicates if the request was successful.

For example:

var result = await _apiClient.UpdateSetup(accountId, setupId, new UpdateModel()
{
    ParameterUpdates = new List<ParameterUpdateModel>()
    {
        new ParameterUpdateModel("Param1", "NewValue")
    },
});

Delete functions​

To update an item using the wrapper use the DeleteXX functions. The ID of the item to be deleted will need to be provided as an argument.

The delete functions return a bool that indicates if the request was successful.

For example:

var result = await _apiClient.DeleteSetup(accountId, setupId);