com.geotab.api

Interface Api

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

GeotabApi

public interface Api
extends Closeable

Used to make API calls against a MyGeotab web server. It makes it easy to invoke the various methods and receive the results. It also automates some tasks such as handling a database that was moved from one server to another or credentials expiring.

All callXxx methods, if the API is not yet authenticated, will issue an authenticate() call automatically before making the actual call. If the user session expires, it will try to re-authenticate using the credentials provided initially.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Api.EntityDescriptor<E extends Entity,S extends Search>
static class	Api.MethodDescriptor<P extends AuthenticatedParameters,R>
static interface	Api.MultiCallBuilder

Field Summary

Fields

Modifier and Type	Field and Description
static String	Add Deprecated. use callAdd(com.geotab.http.request.AuthenticatedRequest<?>) instead.
static String	Get Deprecated. use callGet(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) instead.
static String	GetCountOf Deprecated. use callGetCountOf(com.geotab.http.request.AuthenticatedRequest<?>) instead.
static String	GetFeed Deprecated. use callGetFeed(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) instead.
static String	Remove Deprecated. use callRemove(com.geotab.http.request.AuthenticatedRequest<?>) instead.
static String	Set Deprecated. use callSet(com.geotab.http.request.AuthenticatedRequest<?>) instead.

Method Summary

Modifier and Type	Method and Description
LoginResult	authenticate() Authenticates a user and provides a LoginResult if successful.
Api.MultiCallBuilder	buildMultiCall() Builds a type-safe API multi-call.
<O extends BaseResponse<T>,T> Optional<T>	call(AuthenticatedRequest<?> in, Class<O> outT) Deprecated. use callResult(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) instead and specify the result type instead of the response type.
default <E extends Entity> Optional<Id>	callAdd(Api.EntityDescriptor<E,?> type, E entity) Makes a type-safe Add call.
default Optional<Id>	callAdd(AuthenticatedParameters in) Makes an Add call.
Optional<Id>	callAdd(AuthenticatedRequest<?> in) Makes an Add call.
default <E extends Entity,S extends Search> Optional<List<E>>	callGet(Api.EntityDescriptor<E,S> type, S search) Makes a type-safe Get call.
default <E extends Entity,S extends Search> Optional<List<E>>	callGet(Api.EntityDescriptor<E,S> type, S search, @Nullable Integer resultLimit) Makes a type-safe Get call.
<T extends Entity> Optional<List<T>>	callGet(AuthenticatedRequest<?> in, Class<T> outT) Makes a Get call.
default <T extends Entity> Optional<List<T>>	callGet(SearchParameters<?> in, Class<T> outT) Makes a Get call.
default <E extends Entity> Optional<List<E>>	callGetAll(Api.EntityDescriptor<E,?> type) Makes a type-safe Get call to query all entities.
default <E extends Entity> Optional<E>	callGetById(Api.EntityDescriptor<E,?> type, String id) Makes a type-safe Get call to query by ID.
default <E extends Entity,S extends Search> Optional<Integer>	callGetCountOf(Api.EntityDescriptor<E,S> type, S search) Makes a type-safe GetCountOf call.
Optional<Integer>	callGetCountOf(AuthenticatedRequest<?> in) Makes a GetCountOf call.
default Optional<Integer>	callGetCountOf(SearchParameters<?> in) Makes a GetCountOf call.
default <E extends Entity,S extends Search> Optional<List<E>>	callGetFeed(Api.EntityDescriptor<E,S> type, S search, @Nullable String fromVersion, @Nullable Integer resultLimit) Makes a type-safe GetFeed call.
<T extends Entity> Optional<FeedResult<T>>	callGetFeed(AuthenticatedRequest<?> in, Class<T> outT) Makes a GetFeed call.
default <T extends Entity> Optional<FeedResult<T>>	callGetFeed(GetFeedParameters<?> in, Class<T> outT) Makes a GetFeed call.
<P extends AuthenticatedParameters,R> Optional<R>	callMethod(Api.MethodDescriptor<P,R> method, P in) Makes a web method call.
default <E extends Entity,S extends Search> void	callRemove(Api.EntityDescriptor<E,S> type, E entity) Makes a type-safe Remove call.
default void	callRemove(AuthenticatedParameters in) Makes a Remove call.
void	callRemove(AuthenticatedRequest<?> in) Makes a Remove call.
<T> Optional<T>	callResult(AuthenticatedRequest<?> in, Class<T> outT) Makes a custom method API call specifying the result type.
<T> Optional<List<T>>	callResultList(AuthenticatedRequest<?> in, Class<T> outT) Makes a custom method API call specifying the element type of list result type.
default <E extends Entity> void	callSet(Api.EntityDescriptor<E,?> type, E entity) Makes a type-safe Set call.
default void	callSet(AuthenticatedParameters in) Makes a Set call.
void	callSet(AuthenticatedRequest<?> in) Makes a Set call.
static <E extends Entity,S extends Search> Api.EntityDescriptor<E,S>	entity(Class<E> type)
boolean	isAuthenticated() Check if the API is authenticated.
static <P extends AuthenticatedParameters,R> Api.MethodDescriptor<P,R>	method(String name, Class<? super R> result, Class<?>... parameterClasses)
<O extends BaseResponse<T>,T> Optional<T>	multiCall(MultiCallRequest in, Class<O> outT) Deprecated. use {buildMultiCall()} instead.
<T> Optional<List<T>>	uniformMultiCall(List<? extends BaseRequest<?>> calls, Class<T> outT) Deprecated. use {buildMultiCall()} instead.

Methods inherited from interface java.io.Closeable

close

Field Detail

Add

static final String Add

Deprecated. use callAdd(com.geotab.http.request.AuthenticatedRequest<?>) instead.

Add method name.

See Also:

Constant Field Values

Get

static final String Get

Deprecated. use callGet(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) instead.

Get method name.

See Also:

Constant Field Values

GetCountOf

static final String GetCountOf

Deprecated. use callGetCountOf(com.geotab.http.request.AuthenticatedRequest<?>) instead.

GetCountOf method name.

See Also:

Constant Field Values

GetFeed

static final String GetFeed

Deprecated. use callGetFeed(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) instead.

GetFeed method name.

See Also:

Constant Field Values

Remove

static final String Remove

Deprecated. use callRemove(com.geotab.http.request.AuthenticatedRequest<?>) instead.

Remove method name.

See Also:

Constant Field Values

Set

static final String Set

Deprecated. use callSet(com.geotab.http.request.AuthenticatedRequest<?>) instead.

Set method name.

See Also:

Constant Field Values

Method Detail

authenticate

LoginResult authenticate()

Authenticates a user and provides a LoginResult if successful. It contains the Credentials property that can be used for further API calls. A result of LoginResult.Path = "ThisServer" occurs when the user is found on the current server. Otherwise, a server name is returned and the client must redirect to this new server name.

Maximum 10 Authentication requests per minute, per user.

Throws:

InvalidUserException - Invalid user or password.

DbUnavailableException - Database unavailable.

OverLimitException - Limit overflow.

isAuthenticated

boolean isAuthenticated()

Check if the API is authenticated.

Should be authenticated only after explicit call to authenticate() or any of the callXxx methods.

call

<O extends BaseResponse<T>,T> Optional<T> call(AuthenticatedRequest<?> in,
                                               Class<O> outT)

Deprecated. use callResult(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) instead and specify the result type instead of the response type.

Makes a custom method API call specifying the response type. Always try to use one of the specific method variants * (callGet(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), callGetFeed(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), callAdd(com.geotab.http.request.AuthenticatedRequest<?>), call{Method}, etc.) instead.

callResult

<T> Optional<T> callResult(AuthenticatedRequest<?> in,
                           Class<T> outT)

Makes a custom method API call specifying the result type. Always try to use one of the specific method variants (callGet(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), callGetFeed(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>), callAdd(com.geotab.http.request.AuthenticatedRequest<?>), call{Method}, etc.) instead.

callResultList

<T> Optional<List<T>> callResultList(AuthenticatedRequest<?> in,
                                     Class<T> outT)

Makes a custom method API call specifying the element type of list result type.

callMethod

<P extends AuthenticatedParameters,R> Optional<R> callMethod(Api.MethodDescriptor<P,R> method,
                                                             P in)

Makes a web method call.

WARNING: Experimental API.

callAdd

Optional<Id> callAdd(AuthenticatedRequest<?> in)

Makes an Add call.

callAdd

default Optional<Id> callAdd(AuthenticatedParameters in)

Makes an Add call.

callAdd

default <E extends Entity> Optional<Id> callAdd(Api.EntityDescriptor<E,?> type,
                                                E entity)

Makes a type-safe Add call.

WARNING: Experimental API.

callGet

<T extends Entity> Optional<List<T>> callGet(AuthenticatedRequest<?> in,
                                             Class<T> outT)

Makes a Get call.

callGet

default <T extends Entity> Optional<List<T>> callGet(SearchParameters<?> in,
                                                     Class<T> outT)

Makes a Get call.

callGet

default <E extends Entity,S extends Search> Optional<List<E>> callGet(Api.EntityDescriptor<E,S> type,
                                                                      @Nullable
                                                                      S search)

Makes a type-safe Get call.

WARNING: Experimental API.

callGet

default <E extends Entity,S extends Search> Optional<List<E>> callGet(Api.EntityDescriptor<E,S> type,
                                                                      @Nullable
                                                                      S search,
                                                                      @Nullable
                                                                      @Nullable Integer resultLimit)

Makes a type-safe Get call.

WARNING: Experimental API.

callGetAll

default <E extends Entity> Optional<List<E>> callGetAll(Api.EntityDescriptor<E,?> type)

Makes a type-safe Get call to query all entities.

WARNING: Experimental API.

callGetById

default <E extends Entity> Optional<E> callGetById(Api.EntityDescriptor<E,?> type,
                                                   String id)

Makes a type-safe Get call to query by ID.

WARNING: Experimental API.

callGetCountOf

Optional<Integer> callGetCountOf(AuthenticatedRequest<?> in)

Makes a GetCountOf call.

callGetCountOf

default Optional<Integer> callGetCountOf(SearchParameters<?> in)

Makes a GetCountOf call.

callGetCountOf

default <E extends Entity,S extends Search> Optional<Integer> callGetCountOf(Api.EntityDescriptor<E,S> type,
                                                                             S search)

Makes a type-safe GetCountOf call.

WARNING: Experimental API.

callGetFeed

<T extends Entity> Optional<FeedResult<T>> callGetFeed(AuthenticatedRequest<?> in,
                                                       Class<T> outT)

Makes a GetFeed call.

callGetFeed

default <T extends Entity> Optional<FeedResult<T>> callGetFeed(GetFeedParameters<?> in,
                                                               Class<T> outT)

Makes a GetFeed call.

callGetFeed

default <E extends Entity,S extends Search> Optional<List<E>> callGetFeed(Api.EntityDescriptor<E,S> type,
                                                                          S search,
                                                                          @Nullable
                                                                          @Nullable String fromVersion,
                                                                          @Nullable
                                                                          @Nullable Integer resultLimit)

Makes a type-safe GetFeed call.

WARNING: Experimental API.

callSet

void callSet(AuthenticatedRequest<?> in)

Makes a Set call.

callSet

default void callSet(AuthenticatedParameters in)

Makes a Set call.

callSet

default <E extends Entity> void callSet(Api.EntityDescriptor<E,?> type,
                                        E entity)

Makes a type-safe Set call.

WARNING: Experimental API.

callRemove

void callRemove(AuthenticatedRequest<?> in)

Makes a Remove call.

callRemove

default void callRemove(AuthenticatedParameters in)

Makes a Remove call.

callRemove

default <E extends Entity,S extends Search> void callRemove(Api.EntityDescriptor<E,S> type,
                                                            E entity)

Makes a type-safe Remove call.

WARNING: Experimental API.

multiCall

<O extends BaseResponse<T>,T> Optional<T> multiCall(MultiCallRequest in,
                                                    Class<O> outT)

Deprecated. use {buildMultiCall()} instead.

Makes a type-safe API multi-call.

Response type needs to be constructed based on the multi-call response types expected. The API "result" is going to be an array, where each item is the result of the corresponding call.

Parameters:

in - MultiCallRequest request.

outT - Response type class, used to deserialize the response.

Returns:

The results for the multi-calls.

uniformMultiCall

<T> Optional<List<T>> uniformMultiCall(List<? extends BaseRequest<?>> calls,
                                       Class<T> outT)

Deprecated. use {buildMultiCall()} instead.

Makes a uniform type-safe API multi-call.

All requests must return the same type. This method combine all responses sequentially into a single list. E.g. if 3 device search requests are made and each request returns 2 devices a single list with 6 devices is returned.

WARNING: Experimental API.

Parameters:

calls - List of requests. All request must have the same result type.

outT - The common type of all requests.

Returns:

A flat map of all the request.

buildMultiCall

Api.MultiCallBuilder buildMultiCall()

Builds a type-safe API multi-call. Accumulate request using Api.MultiCallBuilder.callResult(com.geotab.http.request.AuthenticatedRequest<?>, java.lang.Class<T>) and finalize it calling Api.MultiCallBuilder.execute(). The builder can not be reused and Api.MultiCallBuilder.execute() is always the last call.

WARNING: Experimental API.

method

static <P extends AuthenticatedParameters,R> Api.MethodDescriptor<P,R> method(String name,
                                                                              Class<? super R> result,
                                                                              Class<?>... parameterClasses)

entity

static <E extends Entity,S extends Search> Api.EntityDescriptor<E,S> entity(Class<E> type)