com.geotab.api.Api Maven / Gradle / Ivy
/*
*
* 2020 Copyright (C) Geotab Inc. All rights reserved.
*/
package com.geotab.api;
import com.geotab.http.request.AuthenticatedRequest;
import com.geotab.http.request.MultiCallRequest;
import com.geotab.http.response.BaseResponse;
import com.geotab.model.login.LoginResult;
import java.io.Closeable;
import java.util.Optional;
/**
* 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.
*/
public interface Api extends Closeable {
/**
* Authenticates a user and provides a {@link LoginResult} if successful. It contains the {@link
* com.geotab.model.login.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:
*
* - {@link com.geotab.http.exception.InvalidUserException}
* - {@link com.geotab.http.exception.DbUnavailableException}
* - {@link com.geotab.http.exception.OverLimitException}
*
*
* @return A {@link LoginResult} object.
* @throws Exception Exception which can occur while authenticating.
*/
LoginResult authenticate() throws Exception;
/**
* Check if the API is authenticated.
*
* Should be authenticated only after explicit call to {@link Api#authenticate()} or a {@link
* Api#call(AuthenticatedRequest, Class)} method.
*
* @return Whether the API is authenticated or not.
*/
boolean isAuthenticated();
/**
* Makes an API call. If the API is not yet authenticated, then it will issue an authenticate()
* call automatically, before making the actual call.
*
*
If the user session expired, it will try to re-authenticate using the credentials provided
* initially.
*
* @param request Authenticated request.
* @param responseType Response type class, used to deserialize the response.
* @return The result for queries (Get), null for non queries (Set, Remove), id for (Add).
* @throws Exception Exception which can occur while executing the call.
*/
@SuppressWarnings("Indentation")
, ResponseT extends BaseResponse, ResultT>
Optional call(RequestT request, Class responseType) throws Exception;
/**
* Makes an API multi call. It actually delegates to {@link Api#call(AuthenticatedRequest,
* Class)}
*
* 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.
*
* @param request MultiCallRequest request.
* @param responseType Response type class, used to deserialize the response.
* @return The results for the multi calls.
* @throws Exception Exception which can occur while executing the calls.
*/
@SuppressWarnings("Indentation")
, ResultT>
Optional multiCall(RequestT request, Class responseType) throws Exception;
}