Programming Guide to the Hours of Service Platform

Overview

Introduction

The Hours of Service Platform provides a set of cloud-resident services that support the receipt, storage, and manipulation of data from a variety of remote devices. Typical applications of this platform include monitoring and analyzing the movements and other characteristics of people and assets over time by receiving streams of data from these devices. The system exposes its key services to external client applications through a set of RESTful APIs. This document outlines the key objects that form the system and the corresponding service URLs that allow them to be accessed programmatically.

Base URL

Authentication

Most of the Hours of Service API calls require authentication. These calls make use of “basic authentication” in which a user name and password are combined and encoded as “Base-64”. A typical sequence might include these steps:

  1. Concatenate String literals for username, “:”, and for password in the following format <username:password>, i.e., user:password
  2. Encode the concatenated String using Base64 encoding, i.e., DatatypeConverter.printBase64Binary(“user:password”.getBytes(“UTF-8”))
  3. Prepend the String literal “Basic ” to encoded result, i.e., “Basic ” + DatatypeConverter.printBase64Binary(“user:password”.getBytes(“UTF-8”)) resulting in a value of “Basic am9lOnBhc3N3b3Jk”
  4. Include request header named “Authorization” and give it the String value from step three above.

Required Content Headers

  • Content-Type : application/json
  • Authorization : <authentication from previous section, i.e., Basic YWRtaW5AdGVzdDEub3JnOmFkbWlu>

X-Client-Identifier

Any user logged into the portal, android or iOS application sends an optional X-Client-Identifier header. This is to identify where API requests are coming from. Third-party integrators do not use this request header.

  • X-Client-Identifier: VT-Portal;1805
  • X-Client-Identifier: VT-Android/com.azugaeld;1.0.1805.XXXXX
  • X-Client-Identifier: VT-iOS/com.hos.hoursofservice;1805.XXXX.X

Formats

JSON

API responses are returned in JSON format. By default, the JSON is not pretty-printed and appears in a single line. To pretty-print the response, provide the following parameter to the API URL:

  • pretty-print=true

Date and Time

Dates are accepted in multiple formats as follows:

  • June 23, 2014
  • 2014-06-03
  • 2014-06-03T20:00:00Z

All time formats are returned in Coordinated Universal Time (UTC). However, you can submit Date and Times with different time zones. To do this, replace the “Z” format specifier with your added or subtracted hour. Moreover, given that the URL encoded symbol for “+” is “%2B”, appending 2%B06 to a UTC implies UTC + six hours. An example string literal for adding six hours would look like the following: 2014-06-03T20:00:002%B06

Location

For both inputs and outputs, longitude precedes latitude. For example, values (90, 80) imply a longitude of 90 and latitude of 80. Invalid coordinates are as follows:

  • [0, 0]
  • Longitude values outside the range of [-180, 180]
  • Latitude values outside the range of [-90, 90]

In cases where location is not retrieved by the app, the following special coordinates are used:

  • [1000, 1000] – NO_GPS
  • [1001, 1001] – MANUAL_ENTRY
  • [1002, 1002] – MALFUNCTION

Last Changed Date and ID

  • For both the POST and PUT method, JSON entities should not contain a “lastChangedDate” field. This is only retrieved on GET method 
  • For the POST method, JSON entities should not contain an “id” field
  • For the PUT method, JSON entities should contain an “id” field

Pagination (offset and limit)

  • To paginate the results of GET requests, provide the offset parameter. This will retrieve matching records after an offset value (e.g. offset=1000 to get the next 1000 records)
  • To limit the results of GET requests, provide the limit parameter. This will retrieve the number of records specified by the value (e.g. limit=1000 to return only 1000 records)

Common API Error Messages

When an API request to the server results in an exception, the Hours of Service platform returns error messages to the client. Here are the common error messages:

ERROR MESSAGE POSSIBLE CAUSES
Error while handling request The API encountered an error. This may be caused by incorrect JSON data, incorrect parameters or other unexpected exceptions.
<METHOD> is not supported. The method stated is not supported by the API.
User does not have permission to view other user’s data. The method or the API the authenticated user is trying to access is restricted.
There is a problem with the query parameter value. The API encountered a GET error. There is something wrong with the parameters provided.
Entities should not contain an Id when creating.  The API encountered a POST error. The POST request must not have an id field.
Unable to save record The API encountered a POST or PUT error. There is something wrong with the JSON data that the authenticated user is attempting to create or update.
Cannot modify a deleted entity The API encountered a PUT error. The record which the authenticated user is trying to update has already been deleted.
Cannot find requested entity. (id = <ID> ) The API encountered a PUT or DELETE error. The record that the authenticated user is trying to update or delete does not exist in his/her own account.
Entity is already deleted. The API encountered a DELETE error. The record which the authenticated user is trying to delete has already been deleted.
User does not have DELETE role for <API CLASS> The API encountered a DELETE error. The authenticated user does not have access to delete a record under this API.
Driver is Inactive A deactivated driver tries to login