Tools for .NET Clients

For clients of the TrackAbout API who using the .NET framework, TrackAbout provides tools to accelerate implementation. This document provides a walkthrough of using these tools to set up an API client with Visual Studio and C#.

Requirements

• Visual Studio 2012 or newer
• .NET Framework version 4 or newer, or Mono/Xamarin frameworks for Android/iOS

Step 1: Install ServiceStackVS

ServiceStackVS is a Visual Studio extension for building applications using the same framework as the TrackAbout API. Install ServiceStackVS following step 1 of these instructions. Check the notes on that page regarding Visual Studio prerequisites and NuGet to ensure that your IDE is sufficiently up to date.

Step 2: Set up the API client project

Create a new project or open an existing solution in Visual Studio that you will use for the TrackAbout API client. This will be the application or library that will send requests to the API.

Follow these instructions to Add a ServiceStack Reference to your project in Visual Studio. In the Add ServiceStack Reference dialog, enter the following for the Address and Name:

Address: https://test.trackabout.com/api
Name: TrackAboutApi

After clicking OK, the tool will retrieve all of the metadata for the current version of the API in TrackAbout’s test environment, and generate C# class definitions for all request and response objects.

Step 3: Configure and test the API client

At this point, just a few lines of code are needed to implement a basic request and test the API client. You will need to have a TrackAbout API Key and user configured for your test environment; please read the main documentation and contact TrackAbout Support with any questions.

Adapt the following sample code for your project to test the API client:

using ServiceStack;
using TrackAbout.RestApi.Interface.Models;
using TrackAbout.RestApi.Interface.Documentation;

class Program
{
    // Configure these with the appropriate values; consider reading 
    // these values from a config file
    const string ApiKey = "<TrackAbout API key>";
    const string BaseUrl = "https://test.trackabout.com/api";
    const string UserAgent = "<See documentation>";

    static void Main(string[] args)
    {
        // Alternatively, call GetClientWithBasicAuthentication
        var client = GetClientWithToken();
        SendSampleRequests(client);
    }

    static JsonServiceClient GetClientWithToken()
    {
        var client = new JsonServiceClient(BaseUrl);
        client.UserAgent = UserAgent;
        client.Headers["X-Api-Key"] = ApiKey;

        // This sends a POST /api/tokens request to authenticate
        var tokenRequest = new Tokens {
            ApiKey = ApiKey,
            ApplicationInstanceId = UserAgent, // or some other unique ID
            Username = "<username>",
            Password = "<password>"
        };
        var authorizationToken = authClient.Post(tokenRequest);
        client.Headers["X-Token"] = authorizationToken.Token;
        return client;
    }

    static JsonServiceClient GetClientWithBasicAuthentication()
    {
        var client = new JsonServiceClient(BaseUrl);
        client.UserAgent = UserAgent;
        client.Headers["X-Api-Key"] = ApiKey;

        // This configures the Authorization HTTP header
        client.SetCredentials("<username>", "<password>");
        return client;
    }

    static void SendSampleRequests(JsonServiceClient client)
    {
        // This sends a GET /api/locations request
        var locations = client.Get(new AllLocations());
        Console.WriteLine("Got {0} locations, starting with {1}: {2}",
            locations.TotalRows,
            locations.Rows[0].MId,
            locations.Rows[0].Name);

        // This sends a GET /api/fills/new request to retrieve fill records
        var newFills = client.Get(new NewFills { MaxRows = 1 });
        if (newFills.TotalRows > 0)
        {
            // This sends a PUT /api/records/received request to mark 
            // a fill record as having been processed
            var fillId = newFills.Rows[0].TId;
            Console.WriteLine("Got {0} new fills, marking {1} as received now.", newFills.TotalRows, fillId);
            client.Put(new MarkRecordsAsReceived {
                TIds = new List<int> { fillId }
            });
        }
        else
        {
            Console.WriteLine("No new fill records found.");
        }
    }
}

Step 4: Implementing the API client

The sample code in the previous step demonstrates configuring the API client (the JsonServiceClient object), setting up authentication, sending GET and PUT requests, and reading responses. Note that all of the request and response objects are simple C# classes. All JSON serialization is performed automatically, and even the URLs and query string parameters are automatically resolved for you.

The C# classes were generated for you in Step 2, and are located in a .cs file under the .tt file that was added to your project in Step 2. You can browse the contents of the .cs file to see all of the request and response objects available.

To determine how to send a particular request, consult the interactive documentation to find the request. You can then search the .cs file for that request URL; the request object you want to construct is the class that is annotated with that URL. Also, the documentation will explicitly identify the class name for PUT and POST requests. To send a request, construct an object of the appropriate class, and call methods on the JsonServiceClient object such as Get or Post with that request object.

The client has additional capabilities not shown here, such as asynchronous operation and support for mobile clients. Consult the ServiceStack Client documentation for more information.

String constants for HTTP headers, etc.

The dot-net-clients directory in the TrackAbout API GitHub repository has downloadable C# code with definitions for customer HTTP headers and other constants used by the TrackAbout API.

Step 5: Deploying to production

Though the API client code generated in step 2 was based on test.trackabout.com API host, the same code can be used for the TrackAbout production environment without recompiling. Just keep the following in mind:

• Make the API base URL and API key configurable, so that the same code can be deployed to both test and production environments
• If you are using any APIs recently added or updated in the TrackAbout test environment, ensure that those changes have been deployed to TrackAbout's production environment before the API client code in production

Step 6: Updating the API client

When TrackAbout releases updates to the API, you will need to update your client side code. This is as simple as right-clicking the .tt file that was added to the project, and selecting Run Custom Tool. This will regenerate the C# class definitions for API requests and responses.