A robust Application Programming Interface for communicating data directly to various customer and vendor integrations |
DriverTech offers an API to allow Clients to use their own back end systems instead of or in addition to the FleetWatcher Web Portal. This API, known as the FleetWatcher API, is comprised of secure enterprise ready Web Services hosted by servers and networks designed for high availability. The services included in the FleetWatcher API are based upon the same core types as defined in the XSD/WSDL ensuring consistency. Also included is verbose error and exception reporting to speed initial development and enhance the ability to resolve problems programmatically. Service Detail |
Release History | Service | Version | Rev. Date |
---|
Administration | 2.0.80 | 02/02/2015 | Data v2.1 | 2.1.40 | 02/02/2015 | Data v2.0.Test | 2.0.80 | 05/21/2013 | Data v2.0 | 2.0.76 | 12/12/2013 | Data v1.4 | 1.4.50 | 05/20/2013 | Reports | 2.0.75 | 05/20/2013 | PreRelease | 2.0.75 | 05/20/2013 |
|
|
Should you have any questions regarding the services or need assistance please contact Web Service Support via Email
Feel free to contact us for assistance in getting the most out of these Services!
Documentation is provided in the following locations:
- High Level Service Operation information - On each individual service page, below each operation AND in the WSDL linked at the top of each service page via "service reference"
- Detailed Type information - Within annotations in the various XSD files linked at the top of each service page
- Other documents referenced by the service pages - White papers, etc.
- Also available is an XSD Primer for viewing the XSD files mentioned above
Tools and Utilities
Applications which can display an XSD Graphically:
During development of web services it can be very valuable to issue test requests before writing any code:
Service Implementation
High Level Service Information
- All DateTime values are in UTC / GMT - both consumed and provided by the service (see XSD Date Time)
- Many common types are re-used throughout all services to enable developers to apply both DRY, and to a greater extent, SOLID principals:
- DriverBase - provides only enough detail required to identify a specific Driver or Operator
- TruckPCBase - provides only enough detail required to identify a specific Device or ELD
- Position - provides enough detail to pinpoint a location
- FormMessage - provides detail of the content for a particular instance of a Macro or Form
- Detailed Exception Reporting is provided via Soap Faults:
- Server Faults - Should be retried after a limited number of escalating periods of time
- Example
- Client Faults - Shall not be retried as any additional attempt will invoke the same failed response
Example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>XmlSchemaValidationException: The 'http://fwapi.DriverTech.com/CommonTypes/2009/04:CompanyCode' element is invalid - The value '?' is invalid according to its datatype 'String' - The actual length is less than the MinLength value.</faultstring>
<faultactor>http://fwapi.drivertech.com/Data/2_1/DataService.asmx</faultactor>
<detail>
<fault>
<Errors xmlns="http://fwapi.DriverTech.com/CommonTypes/2009/04">
<Error ErrorCategoryId="1000" ErrorCodeId="1109">
<ErrorCode>XmlSchemaValidationFailed</ErrorCode>
<ErrorCategory>Client</ErrorCategory>
<ErrorDescription/>
</Error>
</Errors>
</fault>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope> |
|
- Fault Detail
Data Sourcing Strategies
To prevent disruption by both intentional and unintentional DOS type of 'attacks' your requests will be rate limited as follows:
- Inbound (from Device->DataCenter->You) data requests by Company+User+Operation to not more than 1 every 1000ms
- Outbound (from You->DataCenter->Device) is rate-limited by Company+User+Operation to not more than 1 every 300ms
Guidelines for continual polling of various data types
Type | Recommended | Maximum Frequency | Notes |
DataService: InboundMessages | 5 minutes | 1 minutes | Drain Queue processing may be applied |
DataService: InboundFiles | 10 minutes | 1 minutes | Drain Queue processing may be applied |
DataService: TrailerEvents | varies | 1 minutes | Drain Queue processing may be applied |
DataService: HosTotals | 1 hours | 1 minutes | HosTotals can be continually calculated on the client between polling intervals Its possible to retreive only those which have been updated since the last request |
DataService: HosLogs | 6 hours | 1 hours | Drain Queue processing may be applied |
DataService: HosUnassignedDriving | 30 minutes | 5 minutes | |
ReportsService: ALL | 6 hours | 1 hours | Drain Queue processing may be applied |
Drain Queue Processing is recommended when continually polling for new data
shortPollSleep = 5 //Required sleep amount when polling again immediately
longPollSleep = Storage.GetLongPollSleep("operationName") //3hours - Configurable long wait period
batchSize = Storage.GetBatchSize("operationName") //1000 - Configurable batch size per operation/request type
currentMaxIndexReceived = Storage.GetLastPollingValue("operationName") //Storage area to keep track of last polled value
While(true)
{
response = X_GetByIndex(currentMaxIndexReceived, batchSize)
currentMaxIndexReceived = MAX(response.Items.Id) //Get MAX(object) for query type (i.e. Int for ByIndex, DateTime for other types)
Storage.SetLastPollingValue("operationName", currentMaxIndexReceived) //Persist the value to durable storage to allow the app to continue after a restart
if(COUNT(response.Items) >= batchSize) //Are there more records?
sleep(shortPollSleep) //Immediately call again to get next batch to catch up as there are more 'in the queue'
else
sleep(longPollSleep)
} |
|