Class API

Namespace

Geotab.Checkmate

Assembly

Geotab.Checkmate.ObjectModel.dll

Used to make API calls against a MyGeotab web server. This object is typically used when using the API from a Microsoft .Net language, like C#, VB.Net or managed C++. It makes it easy to invoke the various methods and receive the results. It also automates of some tasks such as handling a database that was moved from one server to another or credentials expiring. This class is thread safe.

public class API : IApi

Inheritance

object

API

Implements

IApi

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

The maximum number of concurrent connections per server is 64, provided by the default HttpMessageHandler. It can be increased/decreased by providing a custom instance of HttpMessageHandler.

Constructors

API(Credentials, ApiClientConfiguration?)

Initializes a new instance of the API class.

public API(Credentials credentials, ApiClientConfiguration? apiClientConfiguration = null)

Parameters

credentials Credentials

The Credentials.

apiClientConfiguration ApiClientConfiguration

The ApiClientConfiguration provided by the API client for custom configurations.

API(string, string?, string?, string, string?, int, HttpMessageHandler?, ApiClientConfiguration?)

Initializes a new instance of the API class.

public API(string userName, string? password, string? sessionId, string database, string? server = null, int timeout = 300000, HttpMessageHandler? handler = null, ApiClientConfiguration? apiClientConfiguration = null)

Parameters

userName string

The user name to use for authentication.

password string

The password to use for authentication. Note: password OR sessionId are required. Both can be supplied.

sessionId string

The session ID if user is already authenticated. Note: password OR sessionId are required. Both can be supplied. If only session ID is supplied the API cannot re-authenticate.

database string

The name of the database the user belongs to.

server string

The server federation name. Default: my.geotab.com. Note: this should NOT be a specific server (my3.geotab.com) databases can be moved to different servers to maximize performance without warning.

timeout int

The timeout for the requests in milliseconds (Default 300000).

handler HttpMessageHandler

The HttpMessageHandler to be used with the HttpClient request. The HttpMessageHandler provides additional control over see cref="HttpClient"/> request. The API object will not dispose of this object.

apiClientConfiguration ApiClientConfiguration

The ApiClientConfiguration provided by the API client for custom configurations.

API(string, string, string, string, string, IWebProxy, int)

Initializes a new instance of the API class.

[Obsolete("proxy has been deprecated and is ignored, if require use of proxy please use constructor with HttpMessageHandler provided", false)]
public API(string userName, string password, string sessionId, string database, string server, IWebProxy proxy, int timeout = 300000)

Parameters

userName string

The user name to use for authentication.

password string

The password to use for authentication. Note: password OR sessionId are required. Both can be supplied.

sessionId string

The session ID if user is already authenticated. Note: password OR sessionId are required. Both can be supplied. If only session ID is supplied the API cannot re-authenticate.

database string

The name of the database the user belongs to.

server string

The server federation name. Default: my.geotab.com. Note: this should NOT be a specific server (my3.geotab.com) databases can be moved to different servers to maximize performance without warning.

proxy IWebProxy

The IWebProxy to use.

timeout int

The timeout for the requests in milliseconds (Default 300000).

Properties

Database

Gets or sets the specific database on the server to which the API call is being made.

public string Database { get; set; }

Property Value

string

A string database name.

LoginResult

Gets or sets the result of the login request.

public LoginResult? LoginResult { get; set; }

Property Value

LoginResult

LoginResult

Password

Sets the user's password.

public string Password { set; }

Property Value

string

string

Proxy

Gets or sets IWebProxy to use in the request />.

[Obsolete("proxy has been deprecated and is ignored, if require use of proxy please use constructor with HttpMessageHandler provided", false)]
public IWebProxy? Proxy { get; set; }

Property Value

IWebProxy

IWebProxy

Server

Gets or sets the name of the server that the API call is being made to.

public string Server { get; set; }

Property Value

string

string

SessionId

Gets or sets the token generated from the authentication call which can be used to make the API call instead of the password.

public string? SessionId { get; set; }

Property Value

string

string

Timeout

Gets or sets the timeout for the requests in milliseconds.

public int Timeout { get; set; }

Property Value

int

int

UserName

Gets or sets the username (typically an email address) that identifies the user being authenticated.

public string UserName { get; set; }

Property Value

string

string

Methods

Authenticate()

Authenticate the user. This method is deprecated. Rather use AuthenticateAsync(CancellationToken)

[Obsolete("Asynchronous AuthenticateAsync method is better for performance.")]
public void Authenticate()

Remarks

The method is marked as Obsolete.

AuthenticateAsync(CancellationToken)

Authenticate the user in an async call.

public Task AuthenticateAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken used to single that the request should be cancelled.

Returns

Task

A Task which is a result of calling AuthenticateImplAsync.

CallAsync<T>(string, object?, CancellationToken)

Make an API request using a non-generic type method. This is an async call.

public Task<T?> CallAsync<T>(string method, object? parameters = null, CancellationToken cancellationToken = default)

Parameters

method string

The method name to call.

parameters object

An anonymous object containing properties (param name) with values (param value). Property name must match that of the method parameter.

cancellationToken CancellationToken

The CancellationToken used to single that the request should be canceled.

Returns

Task<T>

The result for queries and null for non queries (Add, Set, Remove).

Type Parameters

T

The return object type.

CallAsync<T>(string, Type, object?, CancellationToken)

Make an API call using a generic type method. Generic type methods are methods that have the same name but take a specific object type. This is an async call.

public Task<T?> CallAsync<T>(string method, Type type, object? parameters = null, CancellationToken cancellationToken = default)

Parameters

method string

The method name to call.

type Type

The Type use in the generic api call.

parameters object

An anonymous object containing properties (param name) with values (param value). Property name must match that of the method parameter.

cancellationToken CancellationToken

The CancellationToken used to single that the request should be canceled.

Returns

Task<T>

The result for queries and null for non queries (Add, Set, Remove).

Type Parameters

T

The return object type.

Call<T>(string, object?)

Make an API request using a non-generic type method.

[Obsolete("Asynchronous CallAsync method is better for performance.")]
public T? Call<T>(string method, object? parameters = null)

Parameters

method string

The method name to call.

parameters object

An anonymous object containing properties (param name) with values (param value). Property name must match that of the method parameter.

Returns

T

The result for queries and null for non queries (Add, Set, Remove).

Type Parameters

T

The return object type.

Call<T>(string, Type, object?)

Make an API call using a generic type method. Generic type methods are methods that have the same name but take a specific object type.

[Obsolete("Asynchronous CallAsync method is better for performance.")]
public T? Call<T>(string method, Type type, object? parameters = null)

Parameters

method string

The method name to call.

type Type

The Type use in the generic call.

parameters object

An anonymous object containing properties (param name) with values (param value). Property name must match that of the method parameter.

Returns

T

The result for queries and null for non queries (Add, Set, Remove).

Type Parameters

T

The return object type.

Remarks

The method is marked as Obsolete.

Clone()

Creates a new object that is a copy of the current instance.

public object Clone()

Returns

object

A new object that is a copy of this instance.

DownloadAsync(Stream, MediaFile, CancellationToken)

Make an API call using generic type method to Download a stream of data.

public Task DownloadAsync(Stream outputStream, MediaFile mediaFile, CancellationToken cancellationToken = default)

Parameters

outputStream Stream

The Stream to write downloaded binary data to.

mediaFile MediaFile

The MediaFile corresponding to the file to download.

cancellationToken CancellationToken

The CancellationToken used to single that the request should be canceled.

Returns

Task

A Task completed result.

MultiCall(params object[])

Make multiple calls (MultiCall) against the database using a single HTTP request. Each "call" must contain the return Type as the last index.

[Obsolete("Asynchronous MultiCallAsync method is better for performance.")]
public List<object?> MultiCall(params object[] arguments)

Parameters

arguments object[]

A an array of object arrays contain call arguments and Type (if not otherwise specified).

Returns

List<object>

A list of. object

MultiCallAsync(params object[])

Make multiple calls (MultiCall) against the database using a single HTTP request. Each "call" must contain the return Type as the last index. This is an async call.

public Task<List<object?>> MultiCallAsync(params object[] arguments)

Parameters

arguments object[]

A an array of object arrays contain call arguments and Type (if not otherwise specified).

Returns

Task<List<object>>

A list of. object

UploadAsync(Stream, MediaFile, CancellationToken)

Make an API call using generic type method to Upload a stream of data.

public Task UploadAsync(Stream inputStream, MediaFile mediaFile, CancellationToken cancellationToken = default)

Parameters

inputStream Stream

The Stream of binary data to upload.

mediaFile MediaFile

The fully populated MediaFile corresponding to the file to upload.

cancellationToken CancellationToken

The CancellationToken used to single that the request should be canceled.

Returns

Task

A Task completed result.