A MyGeotab API wrapper for both clientside JavaScript and NodeJS
$ npm install --save mg-api-jsTo access the wrapper in the browser, the library needs to be loaded in. This can be done by downloading api.min.js and referencing the file as needed.
Alternatively, this can be done using jsdelivr CDN:
<!-- This will grab the most up to date version of the api wrapper -->
<script src="https://cdn.jsdelivr.net/npm/mg-api-js"></script>
<!-- This will grab the specified version of the api wrapper -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>For more options using jsdelivr, visit the jsdelivr documentation.
Note: As of v2.0.0, the GeotabApi object no longer accepts an authentication callback.
const GeotabApi = require('mg-api-js');
const api = new GeotabApi(authentication[, options]);Credentials are provided to the wrapper in an authentication object. The authentication object is required to successfully create a GeotabApi object, and must conform to one of the following structures:
If you are connecting with the wrapper for the first time, you must pass a username/password combo of a user on the database you are trying to connect to.
const authentication = {
credentials: {
database: 'database',
userName: 'username',
password: 'password'
},
path: 'serverAddress'
}If you do not know the exact server address this can be omitted when using a password, and will route the initial authentication to
my.geotab.com.
If you already have a session, you can pass in the SessionId, and the wrapper will attempt to authenticate using this first.
const authentication = {
credentials: {
database: 'database',
userName: 'username',
password: 'password',
sessionId: '123456...'
},
path: 'serverAddress'
}If using sessionId, you are required to provide the server path.
A session is valid for up to 14 days.
This optional parameter allows you to define some default behavior of the api:
| Argument | Type | Description | Default |
|---|---|---|---|
| rememberMe | boolean | Determines whether or not to store the credentials/session in the datastore | true |
| timeout | number | The length of time the wrapper will wait for a response from the server (in seconds) | 3 |
| newCredentialStore | object | Overrides the default datastore for remembered credentials/sessions | false |
| fullResponse | boolean | Removes error handling and provides full Axios Response Object. More information in the Axios Response section | false |
Example options object:
const dataStore = new YourDefinedDataStore();
const options = {
rememberMe: true,
timeout: 10,
newCredentialStore: dataStore
}By default, the wrapper will use localStorage in browsers, and a LocalStorageMock in node.
If you want to override this behavior, you can provide an instance of a datastore object in the options object when constructing the wrapper.
At minimum, the datastore must have the following methods:
get()set()clear()
By default, all methods and callbacks will return the results of the call directly. Errors are also handled by the wrapper. If you need more control over the call results, see the Axios Response section below.
api.call('Get', { typeName: 'Device', resultsLimit: 100 })
.then( result => {
// Result is the information returned by the server. In this case, it's the 100 devices.
console.log(result);
})
.catch( error => {
// some form of error occured with the request
console.log(error);
});Using callbacks will allow you to pass in your own logic to be executed when the call is complete. The standard pattern for success callback is as follows:
function callbackSuccess(result){
//Your response logic
console.log(result);
}Error callbacks have two parameters: message and error. message is a condensed string form of error for convience. In the case of a non-200 status code failure, error is an instance of Error. In all other cases, it is the full error JSON returned from the API call.
function callbackError(message, error){
//Your response logic
console.log(message);
console.log(error.data);
}For more information on the error JSON structure returned from MyGeotab API, see here.
Note: error parameter in a .catch statement always returns an instance of Error.
The api by default will authenticate when the first call is run. However, if you want to expedite the process, you can use the authenticate method with promises or callbacks:
const api = new GeotabApi(authentication);
await api.authenticate().then( response => console.log('I have authenticated'));
// OR
api.authenticate( success => {
console.log('Successful authentication');
}, (message, error) => {
console.log('Something went wrong');
});Make a request to the database and receive a promise
let myCall = api.call('Get', {
typeName: 'Device',
resultsLimit: 1
});
myCall.then( data => console.log(`Server response data: ${data}`))
.catch( error => console.log(error));Make a request to the database by providing a success/error callback
api.call('Get', {
typeName: 'Device',
resultsLimit: 1
}, function (result) {
if (result) {
console.log(result);
}
}, function (message, err) {
console.error(err);
});Perform multiple queries against the database in a single HTTPS request
let calls = [
['Get', { typeName: 'Device', resultsLimit: 1 }],
['Get', { typeName: 'User', resultsLimit: 1 }]
];
let myMultiCall = api.multiCall(calls);
myMultiCall.then(data => console.log(`Server response: ${data}`))
.catch(error => console.log(error));api.multiCall([
['Get', {
typeName: 'Device',
resultsLimit: 1
}],['Get', {
typeName: 'User',
resultsLimit: 1
}]
], function (result) {
if (result) {
console.log(result);
}
}, function (message, err) {
console.error(err);
});Clears credentials and the credential store.
api.forget();Forget also allows a promise to be returned. By default this returns a fresh set of credentials
let myForgetCall = api.forget();
myForgetCall.then(data => console.log(`Server response: ${data}`))
.catch(error => console.log(error));Retrieves the API user session. Returns the credentials and server.
let mySession = api.getSession();
mySession.then(data => console.log(`Server response: ${data}`))
.catch(error => console.log(error));api.getSession(function (result) {
console.log(result.credentials, result.path);
});Note: This will disable all error checking in the GeotabApi wrapper
In an effort to give you more control over the actual responses, the wrapper can be configured to return an Axios Response Object. This object contains several bits of information about the request and it's response. Response data will be held in the data section of the response.
To enable full response data, simply add the fullResponse: true to the options object when constructing the GeotabApi object:
const GeotabApi = require('mg-api-js');
const opts = {
fullResponse: true
}
const api = new GeotabApi(authentication, opts);If the call to the database is successful, but there is an error with the call itself, the server will return an error object that contains specifics about what went wrong.:
api.call('Get', {typeName: 'Device', resultsLimit: 10})
.then( response => response.data ) // response is the Axios response object
.then( data => {
// This is the server response
data.result; // The successful Call - device information
data.error // Unsuccessful Call - error information
})
.catch( err => console.log(err) );As of v2.0.0, there are several noteable changes that will cause previous implementations of the api wrapper to fail.
Using a credentials callback to instantiate GeotabApi is no longer an option. All credentials must be passed as an authentication object described above
JSONP is no longer supported both as a function and as an argument in the options parameter