Overview

There is an official API client, implemented in C#. It is compatible with .Net 4.0 and higher. There is also version for Windows store apps (portable class library). The API client library is available at Nuget

Alternatively it can be downloaded here

Features

  • Cross platform. Works on .Net 4.0 and higher. There is a portable class library version as well (Windows 8 store apps).
  • Supports all API methods of Trakopolis API server
  • Supports all client types and workflows (PrivateM2M, Web plugins, External/mobile apps)
  • Optional automatic tokens management

Usage

You need to initialize API client with Client Identifier, Client Secret and client type. To do requests to protected resources, an access token should be used or API client should be configured to manage tokens automatically and renew if they are going to expire soon.

Copy 
var apiClient = new TrakopolisApiClient(TrakopolisClientType.PrivateM2M, clientId, clientSecret);
 var token = apiClient.GetAccessToken();
 apiClient.GetAssets(null, token);

Methods names and parameters conventions

All methods that receive data from the Trakopolis API server, starts with "Get" prefix, for example, GetAssets. Methods that update entities, starts from Update and methods that create new entities, starts from Create. Typical Get method has following signature: GetEntity([optional] entity-related parameters, [optional] API Query Parameters, [optional] AccessToken). For example,

Copy 
public Status[] GetStatuses(Int64 assetId, ApiQueryParams apiQueryParams = null, String accessToken = null)
  • Entity-related parameters vary for different methods and entities. It can be an identifier of entity if we want to get a single entity or it can be something different.
  • API Query parameters. See below for details.
  • Access token is a token that will be used during request. If access token is omited and automatic tokens management is enabled, the Trakopolis API client will either re-use existent token or create new one automatically.

API query params

API Query parameters can alter query behavior (for example, return date in UTC format or in local time), restrict search to include only particular data or make it wider and return data for child divisions or inactive assets/terminals. Most important parameters are:

  • DivisionId. Default is null. If specified, then the API client will include DivisionId into URL to restrict data by this division only. If not specified, division will be determined automatically, based on access token.
  • ReturnUTC. Default is true. If ReturnUTC is true, all dates are returnes in UTC time, otherwise dates are converted to local time of division.
  • IncludeChildDivisions. Default is false. If true, then data of all child divisions will be included to this query

In addition, API Query params includes all query parameters that can be used in any queries. Please note that particular API request may ignore some query params.

Automatic tokens management

The Trakopolis API client can automatically renew access tokens when current tokens are going to expire. To start using this feature caller code needs to provide tokens storage that will be used by the API server to get existent tokens and update with new tokens when required.

Copy 
public void EnableAutomaticTokensManagement(ITokensStorage tokensStorage, UInt32 minimumTokenLifetimeSeconds = 30, AccessRevokedDelegate accessRevokedDelegate = null)

ITokensStorage interface represents storage that will be used by the API client. Prior to enabling automatic tokens management this storage must have a token if client type is WebPlugin or External/mobile. This is required to renew access token, based on existent token. The Trakopolis API client has a default in-memory tokens storage implementation that can be used in simple situations.

AccessRevokedDelegate delegate is called if API client failed to renew access token for External application. After delegate is executed, API client throws TrakopolisApiAccessRevokedException for caller code.

Example for PrivateM2M apps

Copy 
apiClient.EnableAutomaticTokensManagement(new MemoryTokenStorage());
 // Do your calls without passing an access token.
 apiClient.GetAssets();

Example for Web plugin / External apps:

Copy 
var token = apiClient.GetAccessToken(...);
 var storage = new MemoryTokenStorage();
 storage.SaveToken(token);
 apiClient.EnableAutomaticTokensManagement(storage);
 // Do your calls without passing an access token.
 apiClient.GetAssets();

By default Trakopolis API client re-uses existent access token if it is valid at least 30 seconds. This value is controlled by minimumTokenLifetimeSeconds method parameter. The Trakopolis API client uses local computer time to detect if token is expired or not. If local clock changed, please update an access token manually.

Automatic tokens management can be disabled by calling method DisableAutomaticTokensManagement.

Please note that if you explicitly passed an access token to method call, it will be used and the Trakopolis API client won't renew token automatically.

Error handling

The Trakopolis API client throws exceptions of 3 types:

  • TrakopolisApiException - generic errors
  • TrakopolisApiParseException - response parsing errors
  • TrakopolisApiAccessRevokedException - API client failed to revew access token, based on refresh token (External applications only)

Exception has detailed information about API request that failed and some information about API server response.