web:access_rest_api
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
web:access_rest_api [2016/01/29 01:10] mjallison [Method Breakdown] |
web:access_rest_api [2016/02/09 00:25] (current) mjallison [Responses] |
||
|---|---|---|---|
| Line 5: | Line 5: | ||
| ===== Use Cases ===== | ===== Use Cases ===== | ||
| - | The Web API (AKA REST) will likely be used in the following use cases: | + | The Web API (AKA REST) will likely be used in the following use cases, in relative priority order: |
| - | * Track viewing operation (AKA TrackManager light) | + | * AGTEK Access file client |
| * Replacement of V1 access.agtek.com application | * Replacement of V1 access.agtek.com application | ||
| * CRUD of customer admin functions | * CRUD of customer admin functions | ||
| Line 12: | Line 12: | ||
| * Supporting mass market items (non-licensed) | * Supporting mass market items (non-licensed) | ||
| * Server monitoring functionality. | * Server monitoring functionality. | ||
| + | * Track viewing operation (AKA TrackManager light) | ||
| + | |||
| + | Implementation notes: | ||
| * Web applications are running as separate WAR apps, perhaps on different machines. | * 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. | * 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 ===== | ===== Method Breakdown ===== | ||
| - | | **Sub-API** | **Method Name** | **Return Value** | **Notes** | | + | | **API-class (priority)** | **Method Name** | **Return Value** | **REST Method** | **params** | **return** | **Notes** | |
| - | | CONNECTION | | | | | + | | CONNECTION (0) | | | | | |
| - | | ASSOCIATION | | | | | + | | | connect() | StorageServer | GET | userid,password,token | GR | |
| - | | | getAssociations() | Association* | | | + | | | connectResetPassword() | | GET | userid,password | GR | **still needed** | |
| - | | | addAssociation() | Association | | | + | | | disconnect() | | PUT | | GR | |
| - | | | updateAssociation() | Association | | | + | | | getAnnouncements() | Announcement* | GET | | GR [ Announcement ] | |
| - | | | deleteAssociation() | Association | | | + | | ASSOCIATION (4) | | | | | |
| - | | CONFIGURATION | | | | | + | | | getAssociations() | Association* | GET | | |
| - | | | getAllConfigurations() | Configuration* | | | + | | | addAssociation() | Association | PUT | | |
| - | | | getConfiguration() | Configuration | | | + | | | updateAssociation() | Association | PUT | | |
| - | | | updateConfiguration() | Configuration | | | + | | | deleteAssociation() | Association | PUT | | |
| - | | | getConfigurationData() | ConfigurationData | | | + | | CONFIGURATION (4) | | | | | |
| - | | | setConfigurationData() | void | | | + | | | getAllConfigurations() | Configuration* | GET | | |
| - | | FILEAPI | | | | | + | | | getConfiguration() | Configuration | GET | | |
| - | | | createFolder() | StoredFolder | | | + | | | updateConfiguration() | Configuration | PUT | | |
| - | | | createPublicUrl() | String url | | | + | | | getConfigurationData() | ConfigurationData | POST | | |
| - | | | deleteFile() | void | | | + | | | setConfigurationData() | void | POST | | |
| - | | | deletePublicUrl() | void | | | + | | FILEAPI (1) | | | | | |
| - | | | downloadFile() | | to file... tbd | | + | | | createFolder() | StoredFolder | GET | path | GR { stedFolder } | |
| - | | | downloadVersion() | | to file... tbd | | + | | | createPublicUrl() | String url | GET | path | GR { url } | |
| - | | | getAccountInfo() | | | | + | | | deleteFile() | void | PUT | path | GR | |
| - | | | getFolder() | StoredFolder | | + | | | deletePublicUrl() | void | PUT | path | GR | |
| - | | | getVersions() | StoredFile+ | | + | | | downloadFile() | | GET | path | | to file... tbd | |
| - | | | getStoredFile() | StoredFile | | | + | | | downloadVersion() | | GET | path | | to file... tbd | |
| - | | | moveFile() | void | | | + | | | getAccountInfo() | | GET | | GR { AccountInfo } | |
| - | | | renameFile() | void | | | + | | | getFolder() | StoredFolder | GET | ??? | |
| - | | | renameFolder() | void | | | + | | | getVersions() | StoredFile+ | GET | | |
| - | | | setDescriptio() | void | | | + | | | getStoredFile() | StoredFile | GET | | |
| - | | | uploadFolder() | StoredFolder | | | + | | | moveFile() | void | PUT | path, dstpath | GR | |
| - | | PROJECTS | | | | | + | | | renameFile() | void | PUT | path, newname | GR | |
| - | | | addProject() | Project | | | + | | | renameFolder() | void | PUT | path, newname | GR | |
| - | | | updateProject() | Project | | | + | | | setDescription() | void | PUT | path, description | |
| - | | | getProjects() | Project* | | | + | | | uploadFolder() | StoredFolder | POST | ??? | |
| - | | | deleteProject() | void | | | + | | | uploadFile() | StoredFile | POST | ??? | |
| - | | | archiveProject() | StoredFile | | | + | | PROJECTS (2) | | | | | |
| - | | | restoreProject() | Project | | | + | | | addProject() | Project | PUT | | |
| - | | | getWorkingTime() | WorkingTime | | | + | | | updateProject() | Project | PUT | | |
| - | | | getWorkingTime() | WorkingTime* | | | + | | | getProjects() | Project* | PUT | | |
| - | | | updatingWorkingTime() | WorkingTime | | | + | | | deleteProject() | void | PUT | | |
| - | | | deleteWorkingTime() | void | | | + | | | archiveProject() | StoredFile | POST | | |
| - | | REPORTS | | | | | + | | | restoreProject() | Project | POST | | |
| - | | | getReportFormats() | String+ | | | + | | | getWorkingTime() | WorkingTime | GET | | | for a day | |
| - | | | getReports() | String+ | | | + | | | getWorkingTime() | WorkingTime* | GET | | | for a range of times | |
| - | | | runReport() | void | | | + | | | updatingWorkingTime() | WorkingTime | PUT | | |
| - | | | getActiveProducts() | String+ | | | + | | | deleteWorkingTime() | void | PUT | | |
| - | | ADMIN | | | All are customer admin functions as defined in current API | | + | | REPORTS (3) | | | | | |
| - | | | getUsers() | StorageUser* | | | + | | | getReportFormats() | String+ | GET | | |
| - | | | addUser() | StorageUser | | | + | | | getReports() | String+ | GET | | |
| - | | | deleteUser() | boolean | | | + | | | runReport() | void | POST | | |
| - | | | updateUser() | StorageUser | | | + | | | getActiveProducts() | String+ | GET | | |
| - | | | getAllLicenses() | LicenseKey* | | | + | | ADMIN (3) | | | | | | All are customer admin functions as defined in current API | |
| - | | | removeLicenseUser() | void | | | + | | | getUsers() | StorageUser* | GET | | |
| - | | | addLicenseUser() | void | | | + | | | addUser() | StorageUser | PUT | | |
| - | | | updateLicenseCheckoutTime() | LicenseKey | | | + | | | deleteUser() | boolean | PUT | | |
| - | | | getLicenseLog() | | | | + | | | updateUser() | StorageUser | PUT | | |
| - | | LICENSE | | | Not supported in V1 | | + | | | getAllLicenses() | LicenseKey* | GET | | |
| - | | SUPPORT | | | Limited to viewing only operations | | + | | | removeLicenseUser() | void | PUT | | |
| - | | TRACKING | | | Plus traditional POSITION API | | + | | | addLicenseUser() | void | PUT | | |
| - | | | getSerialNumbers() | String* | | + | | | updateLicenseCheckoutTime() | LicenseKey | PUT | | |
| - | | | updateGpsStats() | GpsStat | | + | | | getLicenseLog() | | GET | | |
| - | | | updateGpsStats() | GpsStat | inp telemetry, needed in web? | | + | | LICENSE (5) | | | | | | Needed for web apps at all? | |
| - | | | getGpsStats() | GpsStat+ | | | + | | | getLicenses() | LicenseKey* | GET | | |
| - | | | getGpsTelemetry() | GpsTelemetry | | | + | | | checkoutLicense() | LicenseKey | PUT | | |
| - | | | getTracks() | Track* | | | + | | | checkinLicense() | LicenseKey | PUT | | |
| - | | | getTrack() | Track | | | + | | | renewLicense() | LicenseKey | PUT | | |
| - | | | deleteTrack() | void | | | + | | | submitLicenseComment() | void | PUT | | |
| - | | | moveTrack() | Track | | | + | | SUPPORT (5) | | | | | | Limited to viewing only operations | |
| - | | | combineTrack() | Track | | | + | | | getConfig() | Config | GET | | |
| - | | | updateTrack() | void | | | + | | | getCustomers() | StorageCustomer* | GET | | |
| - | | | getTrackStats() | TrackStats | | | + | | | getCustomerByLicense() | StorageCustomer | GET | | |
| - | | | getTrackSummaryStats() | TrackStats | | | + | | | getCustomerByUser() | StorageCustomer | GET | | |
| - | | | updateTrackStats() | TrackStats | | | + | | | getUsers() | StorageUser | GET | | |
| - | | VEHICLES | | | | + | | | findUsersByPattern() | StorageUser | GET | | |
| - | | | getVehicles() | Vehicle* | | + | | | runReport() | | POST | | |
| - | | | addVehicle() | Vehicle | | + | | | <del>addCustomerUser()</del> | StorageUser | | | |
| - | | | updateVehicle() | Vehicle | | + | | | <del>addAnnouncement() </del> | Announcement | | | |
| - | | | deleteVehicle() | Vehicle | | + | | | <del>deleteAnnouncement()</del> | void | | | |
| + | | | <del>getLicenses(cust) </del> | LicenseKey* | | | | ||
| + | | | <del>createLicense() </del> | LicenseKey | | | | ||
| + | | | <del>updateLicense() </del> | LicenseKey | | | | ||
| + | | | <del>convertDCLLicense()</del> | LicenseKey | | | | ||
| + | | | <del>transferLicense()</del> | LicenseKey | | | | ||
| + | | | <del>unlockLicense() </del> | LicenseKey | | | | ||
| + | | | <del>addCustomer()</del> | StorageCustomer | | | | ||
| + | | | <del>updateCustomer()</del> | void | | | | ||
| + | | | <del>getEvents()</del> | String* | | | | Server event list | | ||
| + | | | <del>getApps() </del> | Application | | | | ||
| + | | | <del>updateApp() </del> | | | | | ||
| + | | 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 | | | ||
web/access_rest_api.1454029848.txt.gz · Last modified: 2016/01/29 01:10 by mjallison
Page Tools
