====== AGTEK Access REST Api ======
A REST API into the AGTEK Access system needs to provide full access to the Access server (npi),
and it is desirable to mimic the desktop API in terms of API granularity and specificity.
===== Use Cases =====
The Web API (AKA REST) will likely be used in the following use cases, in relative priority order:
* AGTEK Access file client
* Replacement of V1 access.agtek.com application
* CRUD of customer admin functions
* Running of reports
* Supporting mass market items (non-licensed)
* Server monitoring functionality.
* Track viewing operation (AKA TrackManager light)
Implementation notes:
* Web applications are running as separate WAR apps, perhaps on different machines.
* May need separate instance of REST API for each machine to avoid cross site scripting calls.
* REST API perhaps used for background operations in IOS operations.
===== Responses =====
If the method succeeds, ack is true. Any error will cause ack to be false, and code set to the StorageException value returned by the server. In most cases the string value err is set to the description provided by the error.
{ ack: true|false,
code: 0 | code,
err: "error description"
}
Other JSON structures may be returned from a method. In each case the objects returned are wrapped as a GenericResponse. For instance getAllAnnouncements() returns
{ ack: true|false
code: 0 | code,
err : "error description"
[ Announcement* ]
}
Where **Announcement** is:
{
id: integer,
expire: long, (mSec)
text: "String of announcement"
}
Other return objects possible are:
**StoredItem**
{
handle : int-value,
name : string,
description : string,
isFolder : boolean,
size : long,
children: [ StoredItem* ]
}
**ApplicationState** return from connection/open or connection/check
{
userid: string,
token: string,
lastPath: string,
hasAccess: boolean,
hasLicense: boolean,
hasTracks: boolean,
isAdmin: boolean,
isSupport: boolean
}
**AccountInfo**
{
user: string,
userid: string,
totalSpace: long,
usedSpace: long
}
**StorageUser** (minimal needed for admin functions)
{
handle: integer,
customerId: string,
userId: string,
firstName: string,
lastName: string,
phone: string,
role: string
}
**LicenseKey** (minimal needed for admin functions)
{
handle: integer,
type: integer,
number: string,
customerId: string,
maxCheckoutPeriod: long,
dueDate: long,
checkoutUser: string,
checkoutUserPhone: string
}
**Project**
{
handle: integer,
name: string,
description: string,
lastTrackTime: long,
modifiedTime: long,
status: integer,
trackCount: integer
}
**WorkingTime**
{
projectHandle: integer,
dayStart: long,
morningStart: long,
clipToStart: boolean,
morningEnd: long,
clipToMidday: boolean,
afternoonStart: long,
clipToEnd: boolean,
afternoonEnd: long
}
**Track**
{
handle: integer,
trackerAlias: string,
trackerSerial: string,
projectHandle: integer,
discoveryTime: long,
startTime: long,
endTime: long,
totalPoints: long,
fixType: integer,
attributes: object
}
**TrackPoints**
{
count: integer,
[ Point ]
}
**Point**
{
time: long,
lat: double,
lon: double,
alt: double
}
**Tracker**
{
serial: string,
alias: string,
lastLat: double,
lastLon: double,
lastAlt: double,
lastTime: long,
totalPoints: integer
}
**Telemetry**
{
serial: string,
time: long,
channel: int,
value: numeric | string (depends on channel type)
}
**Vehicle**
{
assetId: string,
type: integer,
status: integer,
description: string,
color: integer, (RGBA 32bit value)
avgLoad: double
}
===== Method Breakdown =====
| **API-class (priority)** | **Method Name** | **Return Value** | **REST Method** | **params** | **return** | **Notes** |
| CONNECTION (0) | | | | |
| | connect() | StorageServer | GET | userid,password,token | GR |
| | connectResetPassword() | | GET | userid,password | GR | **still needed** |
| | disconnect() | | PUT | | GR |
| | getAnnouncements() | Announcement* | GET | | GR [ Announcement ] |
| ASSOCIATION (4) | | | | |
| | getAssociations() | Association* | GET | |
| | addAssociation() | Association | PUT | |
| | updateAssociation() | Association | PUT | |
| | deleteAssociation() | Association | PUT | |
| CONFIGURATION (4) | | | | |
| | getAllConfigurations() | Configuration* | GET | |
| | getConfiguration() | Configuration | GET | |
| | updateConfiguration() | Configuration | PUT | |
| | getConfigurationData() | ConfigurationData | POST | |
| | setConfigurationData() | void | POST | |
| FILEAPI (1) | | | | |
| | createFolder() | StoredFolder | GET | path | GR { stedFolder } |
| | createPublicUrl() | String url | GET | path | GR { url } |
| | deleteFile() | void | PUT | path | GR |
| | deletePublicUrl() | void | PUT | path | GR |
| | downloadFile() | | GET | path | | to file... tbd |
| | downloadVersion() | | GET | path | | to file... tbd |
| | getAccountInfo() | | GET | | GR { AccountInfo } |
| | getFolder() | StoredFolder | GET | ??? |
| | getVersions() | StoredFile+ | GET | |
| | getStoredFile() | StoredFile | GET | |
| | moveFile() | void | PUT | path, dstpath | GR |
| | renameFile() | void | PUT | path, newname | GR |
| | renameFolder() | void | PUT | path, newname | GR |
| | setDescription() | void | PUT | path, description |
| | uploadFolder() | StoredFolder | POST | ??? |
| | uploadFile() | StoredFile | POST | ??? |
| PROJECTS (2) | | | | |
| | addProject() | Project | PUT | |
| | updateProject() | Project | PUT | |
| | getProjects() | Project* | PUT | |
| | deleteProject() | void | PUT | |
| | archiveProject() | StoredFile | POST | |
| | restoreProject() | Project | POST | |
| | getWorkingTime() | WorkingTime | GET | | | for a day |
| | getWorkingTime() | WorkingTime* | GET | | | for a range of times |
| | updatingWorkingTime() | WorkingTime | PUT | |
| | deleteWorkingTime() | void | PUT | |
| REPORTS (3) | | | | |
| | getReportFormats() | String+ | GET | |
| | getReports() | String+ | GET | |
| | runReport() | void | POST | |
| | getActiveProducts() | String+ | GET | |
| ADMIN (3) | | | | | | All are customer admin functions as defined in current API |
| | getUsers() | StorageUser* | GET | |
| | addUser() | StorageUser | PUT | |
| | deleteUser() | boolean | PUT | |
| | updateUser() | StorageUser | PUT | |
| | getAllLicenses() | LicenseKey* | GET | |
| | removeLicenseUser() | void | PUT | |
| | addLicenseUser() | void | PUT | |
| | updateLicenseCheckoutTime() | LicenseKey | PUT | |
| | getLicenseLog() | | GET | |
| LICENSE (5) | | | | | | Needed for web apps at all? |
| | getLicenses() | LicenseKey* | GET | |
| | checkoutLicense() | LicenseKey | PUT | |
| | checkinLicense() | LicenseKey | PUT | |
| | renewLicense() | LicenseKey | PUT | |
| | submitLicenseComment() | void | PUT | |
| SUPPORT (5) | | | | | | Limited to viewing only operations |
| | getConfig() | Config | GET | |
| | getCustomers() | StorageCustomer* | GET | |
| | getCustomerByLicense() | StorageCustomer | GET | |
| | getCustomerByUser() | StorageCustomer | GET | |
| | getUsers() | StorageUser | GET | |
| | findUsersByPattern() | StorageUser | GET | |
| | runReport() | | POST | |
| | addCustomerUser() | StorageUser | | |
| | addAnnouncement() | Announcement | | |
| | deleteAnnouncement() | void | | |
| | getLicenses(cust) | LicenseKey* | | |
| | createLicense() | LicenseKey | | |
| | updateLicense() | LicenseKey | | |
| | convertDCLLicense() | LicenseKey | | |
| | transferLicense() | LicenseKey | | |
| | unlockLicense() | LicenseKey | | |
| | addCustomer() | StorageCustomer | | |
| | updateCustomer() | void | | |
| | getEvents() | String* | | | | Server event list |
| | getApps() | Application | | |
| | updateApp() | | | |
| TRACKING (4) | | | | | | Plus traditional POSITION API |
| | getSerialNumbers() | String* | GET | |
| | updateGpsStats() | GpsStat | PUT | |
| | updateGpsStats() | GpsStat | PUT | | | inp telemetry, needed in web? |
| | getGpsStats() | GpsStat+ | GET | |
| | getGpsTelemetry() | GpsTelemetry | GET | |
| | getTracks() | Track* | GET | |
| | getTrack() | Track | GET | |
| | deleteTrack() | void | PUT | |
| | moveTrack() | Track | PUT | |
| | combineTrack() | Track | PUT | |
| | updateTrack() | void | PUT | |
| | getTrackStats() | TrackStats | GET | |
| | getTrackSummaryStats() | TrackStats | GET | |
| | updateTrackStats() | TrackStats | PUT | |
| VEHICLES (4) | | | | |
| | getVehicles() | Vehicle* | GET | |
| | addVehicle() | Vehicle | PUT | |
| | updateVehicle() | Vehicle | PUT | |
| | deleteVehicle() | Vehicle | PUT | |