About

Examples

All of the example requests are written using curl with bash. The variables service and user are expected to be set. Any Guid's referenced need to be substituted for locally applicable IDs.

Example of setting the environment variables:

export user=John.Doe@mobilelabsinc.com:bca2e6ae-d0c2-4833-9fcd-9446076442a5 export service=http://10.10.0.30

Request Structure

Requests are composed of several components. The URL is structured as protocol://address:port/path?query. POST requests can optionally contain data that is not part of the URL, GET requests can not. The protocol will be http or https depending on your services configuration. The address:port is identical to the one configured for use with GigaFox's web service. The path is always one or more static nouns. Dynamic nouns, such as IDs, and verbs, are in the query. GigaFox's REST API is structured that all requests getting data use GET requests. All requests to modify data use POST requests and return a ResultModel.

Entitlements

Each user is assigned roles with varying degrees of entitlements, allowing users access to certain features, functions, and actions. Once roles are assigned, users will only have access to the entitlements determined by assigned role(s). A full list of entitlements can be found in the Users section of the GigaFox user guide.

Authentification

Authentication is performed using BASIC http authentication with the user's API token as the password.

Requests

Application Requests

GET /Application

Fetch the list of applications stored in GigaFox.

Entitlement: Application list
Query: Optional Application query properties filter
Result: Application[]

Examples:

Fetch the complete list of applications:
curl -u $user "$service/apiv1/Application"

Fetch only the application with the ID 477f5020-fe89-4675-8e6d-92ed4302105a:
curl -u $user "$service/apiv1/Application?id=477f5020-fe89-4675-8e6d-92ed4302105a"

POST /Application?update&id={Guid}

Update the stored application.

Entitlement: Application modify
Result: ResultModel

Query:
Field Type Description
id application GUID The ID of the application to update.
Data:
Field Type Description
Application update properties update A JSON object of the properties to change and their new values.

Examples:

Update the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a DisplayName property to be "New application name":
curl -XPOST -u $user "$service/apiv1/Application?update&id=477f5020-fe89-4675-8e6d-92ed4302105a" \ -H "Content-Type: application/json" \ -d "{DisplayName:\"New application name\"}"

POST /Application?delete&id={Guid}

Delete an application so that it is no longer stored by GigaFox.

Entitlement: Application delete
Result: ResultModel

Query:
Field Type Description
id application GUID The ID of the application to delete.
all bool? If set to true, all applications with the same identifier are deleted. If set to false or excluded, only the application specified by id is deleted.

Examples:

Delete the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a:
curl -XPOST -u $user "$service/apiv1/Application?delete&id=477f5020-fe89-4675-8e6d-92ed4302105a"

POST /Application?add

Upload an application to be stored by GigaFox.

Entitlement: Application upload
Query: None
Data: The application binary.
Result: AsyncResponse<Application>

Examples:

Upload the file "C:\files\deviceControl.ipa" as an application:
curl -XPOST -u $user "$service/apiv1/Application?add" --form "upload=@C:\files\deviceControl.ipa"

POST /Application?action=install&id={Guid}&deviceId={string}

Install a GigaFox stored application to a device.

Entitlement: Device application management
Result: AsyncResponse<ResultModel>

Query:
Field Type Description
id application GUID The ID of the application to install.
deviceId GigaFox ID, serial number, or vendor ID The device to install the application to.
force bool? If set to true, any existing copy of the application is uninstalled and all user data for it is deleted. This may be required when changing signing certificates on iOS or Android. If false or excluded, a normal application installation is attempted.
nativeAutomation bool? If set to true, the application is installed ready for using native automation with Trust automation. If false or excluded, the application is installed normally.

Examples:

Install the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a to the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Application?action=install&id=477f5020-fe89-4675-8e6d-92ed4302105a&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Application?action=uninstall&id={Guid}&deviceId={string}

Uninstall a GigaFox stored application from a given device.

Entitlement: Device application management
Result: ResultModel

Query:
Field Type Description
id application GUID The ID of the application to uninstall.
deviceId GigaFox ID, serial number, or vendor ID The device to uninstall the application from.
removedata bool? If set to true or excluded, the user data for the application is removed. If set to false, the application data is preserved. This would be any files that the application has stored.

Examples:

Uninstall the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a from the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Application?action=uninstall&id=477f5020-fe89-4675-8e6d-92ed4302105a&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Application?action=uninstallBundle&bundleId={string}&deviceId={string}

Uninstall an application by bundle ID from a given device.

Entitlement: Device application management
Result: ResultModel

Query:
Field Type Description
bundleId string The bundle id of the application to uninstall.
deviceId GigaFox ID, serial number, or vendor ID The device to uninstall the application from.
removedata bool? If set to true or excluded, the user data for the application is removed. If set to false, the application data is preserved. This would be any files that the application has stored.

Examples:

Uninstall the application with bundle ID com.mobilelabs.trustbrowser from the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Application?action=uninstall&bundleId=com.mobilelabs.trustbrowser&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Application?action=launch&id={Guid}&deviceId={string}

Launch an application that is installed on a device.

Entitlement: Device connect
Result: AsyncResponse

Query:
Field Type Description
id application GUID The ID of the application to launch.
deviceId GigaFox ID, serial number, or vendor ID The device to launch the application on.
startOnly bool? If set to true, no instrumentation is performed on the application.
arguments string The arguments to send to "am start" on Android, or the arguments to pass to the program on iOS.

Examples:

Launch the application with ID 477f5020-fe89-4675-8e6d-92ed4302105a on the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Application?action=launch&id=477f5020-fe89-4675-8e6d-92ed4302105a&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

Application GUID:
The application GUID is located in the URL of the applications details page.

Device Requests

GET /Device

Fetch the list of devices managed by GigaFox.

Entitlement: Device list
Query: Optional Device query properties filter
Result: Device[]
Notes: The Properties field is not included by default to reduce the amount of data per request. When properties is set, the results of getprop for Android devices and a flattened structure of the lockdownd properties for iOS devices.
Notes: applications is only available when "applications" flag is set.

Query:
Field Type Description
properties bool? Include the Properties field.
applications bool? If set to true, returns the GigaFox managed applications that are installed on the device in installedApplications.
allApplications bool? If set to true, returns all applications that are installed on the device in installedApplications. Applications not managed by GigaFox will have 00000000-0000-0000-0000-000000000000 as their id.

Examples:

Fetch the complete list of devices:
curl -u $user "$service/apiv1/Device"

Fetch only the devices that are online, including the device's properties list in the results:
curl -u $user "$service/apiv1/Device?availability=Online&properties=true"

Fetch only the devices that are enabled and online:
curl -u $user "$service/apiv1/Device?enabled=true&availability=Online"

Fetch the device and application properties for the device with ID 0a7c9243-dj18-44cd-919a-nnd31hhf624:
curl -u $user "$service/apiv1/Device?applications=true&id=0a7c9243-dj18-44cd-919a-nnd31hhf624f&pretty=true"

Fetch a complete list of devices, including installed application data:
curl -u $user "$service/apiv1/Device?applications=true&pretty=true"

GET /Device/Available

Fetch a list of devices with an Available status that the user can retain. The output will not include devices with a Retained/In-Use, Disabled, or Reserved (by another user) status.

Entitlement: Device list
Result: Device[]
Notes: The Properties field is not included by default to reduce the amount of data per request. When properties is set, the results of getprop for Android devices and a flattened structure of the lockdownd properties for iOS devices.
Notes: applications is only available when "applications" flag is set.

Query:
Field Type Description
properties bool? Include the Properties field.
applications bool? If set to true, returns the GigaFox managed applications that are installed on the device in installedApplications.
allApplications bool? If set to true, returns all applications that are installed on the device in installedApplications. Applications not managed by GigaFox will have 00000000-0000-0000-0000-000000000000 as their id.

Examples:

Fetch a list of devices with an Available status:
curl -u $user "http://$server/apiv1/Device/Available"

GET /Device/Log?id={string}

Fetch the device's system log.

Entitlement: Device list
Result: string.

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The device to get the system log for.

Examples:

Fetch the system log for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -u $user "$service/apiv1/Device/Log?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

GET /Device/AppiumLog?id={string}

Fetch the appium stdout/stderr output log.

Entitlement: Device list
Result: string.

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The device to get the system log for.
currentSessionOnly bool? Only return logs for the current (or if session has ended, the last active) session.

Examples:

Fetch the Appium log for the current session for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -u $user "$service/apiv1/Device/AppiumLog?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&currentSessionOnly=true"

POST /Device/WifiConnect?update&id={string}&ssid={string}&passphrase={string}

Connect to the specified wifi network.

Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to change settings on.
ssid string The SSID of the wifi network to connect to.
passphrase string The passphrase for the given wifi network.

Examples:

To connect to networkname on device with ID 00da1f3821494955:
curl -XPOST -u $user "$service/apiv1/Device/WifiConnect?update&id=00da1f3821494955&ssid=networkname&passphrase=mypassphrase"

POST /Device/WifiEnable?update&id={string}&enabled={bool}

Connect to the specified wifi network.

Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to change settings on.
enabled bool true to enable wifi, false to disable.

Examples:

Disable wifi on device with ID 00da1f3821494955:
curl -XPOST -u $user "$service/apiv1/Device/WifiEnable?update&id=00da1f3821494955&enabled=false"

POST /Device?delete&id={string}

Delete a device that is no longer managed by GigaFox. This can only be done to offline devices.

Entitlement: Device list, Device delete
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to delete.

Examples:

To delete device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device?delete&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Device?update&id={string}

Update the stored device model.

Entitlement: Device list, Device modify
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to update.
Data:
Type Description
Device update process A JSON object of the properties to change and their new values.

Examples:

Update the note field for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6 to say "This device is in-use by automation.":
curl -XPOST -u $user "$service/apiv1/Device?update&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6" \ -H "Content-Type: application/json" \ -d "{Notes:\"This device is in-use by automation.\"}"

POST /Device/UsbPort?update&id={string}&usbHubPortState={UsbHubPortState}

Update the state of a USB hub port. This allows alternative a device's USB hub port between disconnect, charging, and data modes.

Entitlement: Manage USB hubs
Result: ResultModel

, or *
Query:
Field Type Description
id GigaFox ID, serial number, or vendor IDThe ID of the device to update. If * is specified, then all devices are targeted.
usbHubPortState UsbHubPortState The state to transition the USB hub port to.

Examples:

Change the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6 usb hub port state to charging:
curl -XPOST -u $user "$service/apiv1/Device/UsbPort?update&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&usbHubPortState=Charge"

Change all devices usb hub port state to data:
curl -XPOST -u $user "$service/apiv1/Device/UsbPort?update&id=*&usbHubPortState=Data"

POST /Device?action=reboot&id={string}

Reboot the operating system on the device. The device's availability will show Offline until the reboot has completed.

Entitlement: Device reboot
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to reboot.

Examples:

Reboot the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device?action=reboot&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Device?action=retain&id={string}

Set a device as retained by the authenticated user inside GigaFox. This prevents other users from performing most actions on the device. See the GigaFox user's guide for more details.

Entitlement: Device connect
Result: ResultModel<DeviceAccessTicket>

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to retain.

Examples:

Retain the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device?action=retain&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Device?action=release&id={string}

Release the retain held on a device.

Entitlement: If not the owner of retain, "Device release any"
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to release.

Examples:

Release the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device?action=release&id=1c32079b-53bc-4-bc4-bcf6-71444a7e6bb6"

POST /Device?action=enable&id={string}

Enable a device to be managed by GigaFox. While a device is disabled, it can not be used but does not count toward the licensed device limit.

Entitlement: Device enablement
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to enable.

Examples:

Enable the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device?action=enable&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Device?action=disable&id={string}

Disable a device so it is no longer accessible from GigaFox. While a device is disabled, it can not be used but does not count toward the licensed device limit.

Entitlement: Device enablement
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to disable.

Examples:

Disable the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device?action=disable&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

POST /Device?action=reset&id={string}

Reset the state of a device. Resetting device state is to permit increased determinacy of the device's state between usage or testing sessions.

Entitlement: If uninstallAll is enabled, "Device application management", if reboot is enabled, "Device reboot."
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to reset.
uninstallAll bool? If set to true, all user installed applications on the device will be uninstalled. If false, no applications are uninstalled. If excluded, the default inside GigaFox's System area is used.
reboot bool? If set to true, the device is reboot. If false, no reboot is performed. If excluded, the default inside GigaFox's System area is used.

Examples:

Reset the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device?action=reset&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

Metrics Requests

GET /Device/Metrics?id={string}&table={string}

Query the device metrics database for specified metrics for a given device.

Entitlement: Device list
Result file

Metrics are gathered passively in the background for all devices managed by GigaFox, unless explicitly disabled. The metrics collected are to the best available for the given device which has some variance as documented. The metrics are stored in an InfluxDB service, which has some implications as documented.

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device to query metrics for.
table string

Tables to select fields from. Formatted as a comma delineated list of measurement names. Table names are listed in the metrics schema.

Example: &table=event, &table=event,log

Warning: Referencing more than one table in a single query has a severe performance impact in InfluxDB.

fields string? A list of fields to select. If excluded, all fields from the referenced tables will be returned. Referencing specific fields can drastically decrease the response size. Formatted as a comma delineated list of fields. Field names are listed in the metrics schema.
aggr string?

A list of functions to perform on the referenced fields. When used, "fields" becomes a required argument. Formatted as a comma delineated list. Each function is implicitly given each listed field as the first argument. The function list is shown in influxdata.

Example: Get the max aggregate of 2 fields. &aggr=max&fields=fieldA,fieldB performs the query as SELECT max(fieldA), max(fieldB)

Example: Get the max aggregate and mean of 2 fields. &aggr=max,mean&fields=fieldA,fieldB performs the query as SELECT max(fieldA), max(fieldB), mean(fieldA), mean(fieldB)

marker string? The name of a marker. When used, the results are limited to the intermediate periods for the most recent specified markers. The marker session is automatically inserted for the periods of time when a device is retained. Custom markers can be inserted using the startmarker and stopmarker API actions. When a marker is specified, start and end are ignored.
Example: Get the metrics for the last 5 sessions.
&marker=session&markerLimit=5
markerLimit int? The number of number of marker entries to reference. If not specific, defaults to 1. Having a markerLimit greater than 1 produces multiple timelines in a single result and may not be directly processable. This is a side effect of InfluxDB.
markerOffset int? The number of markers to skip. For example, if markerLimit is 1, and markerOffset is 3, then the 4th previous marker entry will be used.
limit int? Limit the result rows to the specified limit. If not set, there is no limit. limit can be used with offset to "page" results in smaller portions. limit is required if marker, start, and end are not present.
offset int? The result row to start at. Can only be specified if limit is also specified.
start DateTime?
end DateTim? The time range to limit the query to. Both do not need to be specified. These values are ignored if marker is present.
groupBy string? A field name to group the results by.
orderBy string? A field name to order the results by. Due to limitations in InfluxDB, at present only the time field is supported. An ordering direction can be specified after a space in the field name. Ascending is assumed, desc can be specified manually.
Example: Order by time descending. &orderBy=time+desc
format string? The format of the result. Possible values are csv and default. If CSV is not given, default is assumed. default is a pass-through of the JSON returned by InfluxDB. This permits any InfluxDB result processing tool to be used. Documentation of the format is available on their site: influxdata csv is a transcoding of the JSON to CSV format. CSV is beneficial in it may be less CPU intensive to process,could consume less bandwidth, and has compatibility with any CSV processing application.
filename string? The filename for the returned document. If not specified, the default is "metrics-" followed by the device's name. The extension is automatically set according to the specified format.
timeout int? The optional number of seconds to allow the query to run. The default is 120 seconds. This may need to be adjusted for more complex or larger queries.

Examples:

Get the mean CPU usage during for the last usage session for device ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -u $user "$service/apiv1/Device/Metrics?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&marker=session&aggr=mean&table=sample&fields=Load"

Download all metrics from the sample table to a CSV file for the last usage session for device ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -OJ -u $user "$service/apiv1/Device/Metrics?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&marker=session&table=sample&format=csv"

POST /Device/Metrics?action=startmarker&id={string}&name={string}

Start a metrics marker. The marker must be ended using stopmarker. The marker's timespan is represented by when the startmarker and stopmarker calls were made. Markers are used as named reference points into the metrics timeline. Multiple calls to startmarker can be made before calling stopmarker given each call has a unique name.

Entitlement: Device list
Result: ResultModel

Query:
Field Type Description
id GigaFox ID, serial number, or vendor ID The ID of the device.
name string The name of the marker. There are no character limitations.

Examples:

Start a metrics marker by the name "account-login" for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device/Metrics?action=startmarker&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&name=account-login"

POST /Device/Metrics?action=stopmarker&id={string}&name={string}

End the metrics marker of the same name for the same device as passed to startmarker.

Entitlement: Device list
Result: ResultModel

Query:
Field Type Description
id Guid GigaFox ID, serial number, or vendor ID
name string The name of the marker which was passed to startmarker.

Examples:

Ends the metrics marker by the name "account-login" for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device/Metrics?action=stopmarker&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&name=account-login"

The metrics for the last marker named "account-login" can now be queried like:
curl -XPOST -u $user "$service/apiv1/Device/Metrics?id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&table=sample&marker=account-login"

POST /Device/Metrics?action=enabled&id={string}&enable={bool}

Enable or disable passive metric logging for a device. By default, all devices have passive logging enabled. It's recommended that this be turned off if the performance overhead on the device is detrimental to testing.

Entitlement: Device list, Device modify
Result: ResultModel

Query:
Field Type Description
id Guid GigaFox ID, serial number, or vendor ID
enable bool Set to true if metrics should be passively logged for this device.

Examples:

Disable passive metrics monitoring for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -XPOST -u $user "$service/apiv1/Device/Metrics?action=enabled&id=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6&enable=false"

User Requests

GET /User

Fetch the list of GigaFox users.

Entitlement: Without "User list", only the authenticated user is returned.
Data: Optional User query properties filter.
Result: User[]

Examples:

Fetch all users:
curl -u $user "$service/apiv1/User"

Fetch all users who have the postal code "90210":
curl -u $user "$service/apiv1/User?PostalCode=90210"

POST /User?update&id={Guid}

Modify a specified user record.

Entitlement: "User modify" to modify any user, "User modify self" to modify authenticated user.
Result: ResultModel

Query:
Field Type Description
id Guid The ID of the user.
Data:
Type Uses Description
User update properties update A JSON object of the properties to change and their new values.

Examples:

Update the user with ID 571c211e-96d8-4dad-b11d-7e5e80e2c5fb first name to "John" and last name to "Doe":
curl -XPOST -u $user "$service/apiv1/User?update&id=571c211e-96d8-4dad-b11d-7e5e80e2c5fb" \ -X POST -H "Content-Type: application/json" \ -d "{LastName:\"Doe\",FirstName:\"John\"}"

POST /User?add

Create a new GigaFox user.

Entitlement: User import
Result: ResultModel

Data:
Type Description
User The model of the new user to create.

Examples:

Create a user with the username John.Doe@MobileLabsInc.com, the password correcthorsebatterystaple, and the name "John Doe":
curl -XPOST -u $user "http://10.4.5.135/apiv1/User?add" \ -X POST -H "Content-Type: application/json" \ -d "{Email:\"John.Doe@MobileLabsInc.com\",Password:\"correcthorsebatterystaple\",isActive:\"true\",LastName:\"Doe\",FirstName:\"John\"}"

Report Requests

GET /Report/Availability

Fetch device availability and use history.

Entitlement: User list, Device list, Application list

Query:
Field Type Description
days int? Only events newer than this many days old are returned. Used instead of fromDate.
fromDate DateTime? Only events newer than the provided date are returned. If excluded, there is no minimum date.
toDate DateTime? Only events older than the provided date are returned. If excluded, there is no maximum date.
window DateTime? Only events within the set period of time. A time period with 30 second intervals would be window=00:00:30.

Examples:

Fetch device availability every 30 seconds:
curl -u $user "$service/apiv1/Report/Availability?window=00:00:30&pretty=true"

Fetch device availability stating from April 1, 2019:
curl -u $user "$service/apiv1/Report/Availability?toDate=04-01-2019&pretty=true"

GET /Report/History

Fetch an action history report.

Entitlement: User list, Device list, Application list
Result: EventHistory

Query:
Field Type Description
applicationId Guid? Return only history for the application with this ID. If excluded, all applications are returned.
deviceId GigaFox ID, serial number, or vendor ID Return only history for the specified device. If excluded, all devices are returned.
userId Guid? Return only history for the user with this ID. If excluded, all users are returned.
fromDate DateTime? Only events newer than the provided date are returned. If excluded, there is no minimum date.
toDate DateTime? Only events older than the provided date are returned. If excluded, there is no maximum date.
days int? Only events newer than this many days old are returned. Used instead of fromDate.
skip int? The numeric starting entry to return the history from. Can be used in conjunction with take to paginate results.
take int? The maximum number of entries to return. Can be used in conjunction with skip to paginate results.

Examples:

Get all events from the past 5 days performed by user with ID 571c211e-96d8-4dad-b11d-7e5e80e2c5fb:
curl -u $user "$service/apiv1/Report/History?days=5&userId=571c211e-96d8-4dad-b11d-7e5e80e2c5fb"

GET /Report/Usage

Fetch a device usage history report.

Entitlement: User list, Device list, Application list
Result: DeviceUsageHistory

Query:
Field Type Description
applicationId Guid? Return only history for the application with this ID. If excluded, all applications are returned.
deviceId GigaFox ID, serial number, or vendor ID Return only history for the specified device. If excluded, all devices are returned.
userId Guid? Return only history for the user with this ID. If excluded, all users are returned.
fromDate DateTime? Only events newer than the provided date are returned. If excluded, there is no minimum date.
toDate DateTime? Only events older than the provided date are returned. If excluded, there is no maximum date.
days int? Only events newer than this many days old are returned. Used instead of fromDate.
skip int? The numeric starting entry to return the history from. Can be used in conjunction with take to paginate results.
take int? The maximum number of entries to return. Can be used in conjunction with skip to paginate results.

Examples:

Get all usage records from the past 7 days for the device with ID 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6:
curl -u $user "$service/apiv1/Report/Usage?days=7&deviceId=1c32079b-53bc-4bc4-bcf6-71444a7e6bb6"

Service Requests

GET /Service

Fetch GigaFox history service installation information.

Entitlement: System configuration area access
Result: HubInformation

Examples:

Fetch the results:
curl -u $user "$service/apiv1/Service?pretty=true"

Gateway Requests

GET /Gateway

Fetch information about the attached device gateways and any associated USB hubs and their attached devices.

Entitlement: View gateways
Result: GatewayDescription[]

Examples:

Fetch the device gateway information:
curl -u $user "$service/apiv1/Gateway"

POST /Gateway/UsbHub?update&id={string}&usbHubPort={int}&usbHubPortState={UsbHubPortState}

Change the port state to usbHubPort for the port number given as usbHubPort on the USB hub given as a serial number in id.

Entitlement: Manage USB hubs
Result: ResultModel

Query:
Field Type Description
id string The serial number for the USB hub.
usbHubPort int The numerical port number of the USB hub port to change.
usbHubPortState UsbHubPortState The state to transition the port to.

POST /Gateway/UsbHub?action=reboot&id={string}

Reboot a USB hub. This is a diagnostic action and should be rarely required.

Entitlement: Manage USB hubs
Result: ResultModel

Query:
Field Type Description
id string The serial number of the USB hub to reboot.

Async Requests

GET /Async?id={Guid}

Query an async result's state. See Async for more information.

Entitlement: none
Result: AsyncStatus<T>

Query:
Field Type Description
id Guid The async ID.

Async

Some requests take longer than a HTTP request can be held open. These requests return an AsyncResponse. The status of the request must then be polled using Get /Async.

Get Async will return a false value in isComplete until either an error or success occurs, then isComplete will be true, and data will be populated with the result. Once a completed status is returned, the async ID is invalidated and can no longer be used. Async results that have not been polled in 5 minutes are invalidated.

Metric Schema

The table names usb_hub, log, health_check, and sample. The column device_id is consistent across all tables.

usb_hub

Information regarding the device's USB connection and battery information when available.
Type Description
device_id The device ID.
voltage The current voltage on the USB hub's v5 line.
amperage The amperage draw the device is placing on the USB hub.
wattage The wattage draw the device is placing on the USB hub.
usb_state The state of this USB port. Possible values are Off, Sync, or Charge.
charging_profile When the device is in Charge state, the profile used by the Cambrionix USB hub to charge the device. No further information is available on this at this time.
charging_seconds When the number of seconds the device has been in the Charge state.
battery_percentage If available, the percentage of battery reported by the device.
battery_status If available, the status of the battery reported by the device. Possible values are Unknown, Charging, Discharging, NotCharging, Full.

log

Logs as printed from the device.
Type Description
device_id The device ID.
log The textual contents of the log line.

health_check

Health check status for a device. If device health checks are enabled, GigaFox will periodically verify that device communication is working as expected and record the results here.
Type Description
device_id The device ID.
elapsed_seconds The number of seconds taken to complete the health check.
is_error True if the health check failed, false otherwise.
failure_reason If a health check failed, an error message.

sample

A sample taken from the device. The fields are dynamic, as different devices have different capabilities. There may be fields available that are not listed, and some listed fields may not always be available.
  • iOS and Android
    • device_id
    • Memory
      • Wired
      • Used
      • Free
      • Active
      • Inactive
    • Network
      • Bytes Out
      • Bytes In
      • Bytes Out Per Second
      • Bytes In Per Second
    • CPU
      • Load
      • User Load
      • System Load
  • iOS only
    • Memory
      • VM Swap Used
      • VM Page Out Bytes
      • VM Page In Bytes
    • Disk
      • Bytes Written
      • Bytes Read
      • Bytes Written Per Second
      • Bytes Read Per Second
      • Write Ops Per Second
      • Read Ops Per Second
      • Write Ops
      • Read Ops
    • Network
      • Packets out
      • Packets in
      • Packets In Per Second
      • Packets Out Per Second
    • CPU
      • Nice Load
      • Threads
      • The total sum of threads on all processes.
  • Android only
    The Android only memory metrics can be referenced to from /proc/meminfo in man7.org.
    Graphics information is only available if there's a process that was launched by GigaFox. What entries are available under Graphics varies between Android versions. More information can be found in developer.android.com.
    • Network
      • Errors Out
      • Dropped Out
      • Errors In
      • Dropped In
    • CPU
      • IO Wait Load
      • IRQ Load
      • Frequency
    • Memory
      • Buffers
      • Cached
      • Active (anon)
      • Inactive (anon)
      • Active (file)
      • Inactive (file)
      • User Total (HighTotal)
      • User Free (HighFree)
      • Kernel Total (LowTotal)
      • Kernel Free (LowFree)
      • AnonPages
      • Mapped
      • Kernel Stack
      • Page Tables
      • Commit Limit
      • Committed_AS
      • Vmalloc Total
      • Vmalloc Used
      • Vmalloc Chunk
    • Graphics
      • Total frames rendered
      • Janky frames (count)
      • Janky frames (percent)
      • 90th percentile
      • 95th percentile
      • 99th percentile
      • Number Missed Vsync
      • Number High input latency
      • Number Slow UI thread
      • Number Slow bitmap uploads
      • Number Slow issue draw commands
      • TextureCache Current
      • TextureCache Total
      • LayerCache Current
      • LayerCache Total
      • RenderBufferCache Current
      • RenderBufferCache Total
      • GradientCache Current
      • GradientCache Total
      • PathCache Current
      • PathCache Total
      • TessellationCache Current
      • TessellationCache Total
      • TextDropShadowCache Current
      • TextDropShadowCache Total
      • PatchCache Current
      • PatchCache Total
      • FontRenderer 0 A8 Current
      • FontRenderer 0 A8 Total
      • FontRenderer 0 RGBA Current
      • FontRenderer 0 RGBA Total
      • FontRenderer 0 total Current
      • FontRenderer 0 total Total
      • FboCache Current
      • FboCache Total
      • Total graphics memory

Models

Enums

Enums are passed as strings.

Type Description
DeviceAvailabilityStatus Offline, Online
ApplicationFormFactor Universal, Phone, Tablet
DeviceBatteryStatus Unknown, Charging, Discharging, NotCharging, Full
EventType DeviceAvailability, DeviceRetained, DeviceEnablement, DeviceOperatingSystemChange, DeviceDeletion, ApplicationLaunch, ApplicationInstall, UserLogin, UserCreated, ServerStarting, ServerRestarting, Note
DeviceOperatingSystem Unknown, iOS, Android
DeviceFormFactor Unknown, Phone, Tablet
DevicePropertyType System
UsbHubPortState Unknown, Off, Sync, Charge
UsbHubDeviceFlags None, Off, Sync, Biased, ChargeIdle, ChargeProfiling, ChargeCharging, ChargeFinished, Attached, Detached, Errors, Rebooted, VBusReset

Models

Application

Field Type
id Guid
displayName string
applicationIdentifier string
version string
buildVersion string
Operating System DeviceOperatingSystem
minimumOperatingSystemVersion string
applicationBlob string
originalApplicationBlob string
fileName string
remotePort int
versionCounter int
iconBlob string
fileByteCount long
vendorApplicationName string
provisionExpirationDate DateTime?
provisionsAllDevices bool
signingCertificateName string
isSigningCertificatePresentInEmbeddedProvisi onProfile bool
supportedFormFactors ApplicationFormFactor
applicationErrors string[]
enabled bool
createdDate DateTime
appTeamIdentifier string
trustDylibTeamIdentifier string
isTrustDylibEmbeddedInApp bool
notes string

Device

Field Type
id Guid
availability DeviceAvailabilityStatus
retainedById Guid?
retainedByDisplayName string
enabled bool
batteryStatus DeviceBatteryStatus
batteryPercentCharged int
diskSpace long
slotNumber int?
diskSpaceUsed long
nextReservationStartTime DateTime?
nextReservationEndTime DateTime?
reservedById Guid?
reservedByDisplayName string
lastInuseAt DateTime?
lastDisconnectedAt DateTime?
lastConnectedAt DateTime?
deleted bool
notes string
retainedByUserName string
name string
model string
operatingSystem DeviceOperatingSystem
operatingSystemVersion string
macAddress string
serialNumber string
manufacturer string
friendlyModel string
vendorUniqueIdentifier string
vendorDeviceName string
deviceClass string
formFactor DeviceFormFactor
productType string
isAudioEnabled bool
hardwareModel string
operatingSystemBuild string
usbHubSerialNumber string
usbHubPortNumber int
usbLocation string
bluetoothAddress string
properties DeviceProperty[]
application Application[]

DeviceProperty

Field Type
name string
value string
type DevicePropertyType

User

Field Type
id Guid
email string
isActive bool
firstName string
middleName string
lastName string
notes string
organization string
title string
location string
address1 string
address2 string
city string
region string
postalCode string
country string
homePhone string
mobilePhone string
officePhone string
faxPhone string
createdDate DateTime?
lastLoginDate DateTime?
roles string[]
properties UserProperty[]

UserProperty

Field Type
name string
value string

Event

Field Type
id Guid
deviceId Guid?
deviceName string
eventType EventType
EventDate DateTime
performedById Guid?
performedByName string
intValue int
boolValue bool
stringValue string
message string
isSuccess bool
propertiesId Guid?
applicationName string
userId Guid?
deviceInuseCount int
deviceOnlineCount int

DeviceUsageSummary

Field Type
id Guid
deviceId Guid
deviceName string
performedById Guid?
performedByName string
applicationId Guid?
applicationName string
reservedById Guid?
reservedByName string
eventType EventType
operatingSystem DeviceOperatingSystem
operatingSystemVersion string
startDate DateTime
endDate DateTime
duration TimeSpan
isDirty bool

EventHistory

Field Type
count int
pageSize int
events Event[]

DeviceUsageHistory

Field Type
count int
pageSize int
deviceUsage DeviceUsageSummary[]

GatewayDescription

Field Type
name string
publicAddress string
publicPort int
usbHubList UsbHub[]

UsbHub

Field Type
name string
location string
serialNumber string
description string
model string
firmware string
firmwareDate string
uptime TimeSpan
fiveVoltNow double
fiveVoltMin double
fiveVoltMax double
errorMessage string
isErrored bool
devices UsbHubDevice[]

UsbHubDevice

Field Type
name string
location string
serialNumber string
usbHubSerialNumber string
usbHubPortNumber int
milliamps int
state UsbHubPortState
flags UsbHubDeviceFlags
chargingTime TimeSpan
chargingProfile string

DeviceAccessTicket

Field Type
authenticator string
gatewayAddress string
gatewayPort int
deviceVendorUniqueIdentifier string
serialNumber string

Result<T>

The success of an action with an optional data component attached. Any model defined as returning ResultModel does not have data at anytime.

Field Type Description
isSuccess bool If the query operation was successful.
errorMessage string? A textual message of the error that happened. Excluded if isSuccess is true.
data T? The resulting data. Excluded if isSuccess is false.

AsyncResponse

Field Type
asyncResponseId Guid

AsyncStatus<T>

Field Type
isComplete bool
data T?

Properties

Application

Field Type Uses
Id Guid query
displayName string query; update
ApplicationIdentifier string query
Version string query
buildVersion string query
OperatingSystem string query
MinimumOperatingSystemVersion string query
ApplicationBlob string query
OriginalApplicationBlob string query
FileName string query

Device

Field Type Uses
Id Guid query
Name string query; update
SlotNumber string query; update
Enabled bool query; update
Deleted bool query; update
Notes string update
OperatingSystem string query
Availability string query

User

Field Type Uses
Id Guid query
UserName string query; update
IsActive string query; update
FirstName string query; update
MiddleName string query; update
LastName string update; update
Notes string query; update
Organization string query; update
Title string query; update
Location string query; update
Address1 string query; update
Address2 string query; update
City string query; update
Region string query; update
PostalCode string query; update
Country string query; update
HomePhone string query; update
MobilePhone string query; update
OfficePhone string query; update
FaxPhone string query; update
Password string update

AppiumInformation

Field Type Description
path string Path of the Appium configuration.
version string The GigaFox managed patch version.
pathHash string The GigaFox managed patch version.

XcodeInformation

Field Type Description
path string The Xcode installation path.
versionString string Xcode version
version string Xcode version
buildVersion string The Xcode build version.

HubInformation

Field Type Description
deviceConnectNodeId string The unique licensed node ID of the hub service.
GigaFoxVersion string The GigaFox version installed on the server.
systemDateTime DateTime The local date/time of the server.
systemDateTimeUtc DateTime The UTC date/time of the server.
deviceGatewayInformation GatewayInformation[] Information regarding the connected device gateway servers.

DeviceGatewayInformation

Field Type Description
GigaFoxId string The unique licensed node ID of the hub service.
GigaFoxVersion string The GigaFox version installed on the server.
systemDateTime DateTime The local date/time of the server.
systemDateTimeUtc DateTime The UTC date/time of the server.
deviceVendorUniqueIdentifiers string[] The list of vendor unique device IDs attached to this device gateway.
xcode XcodeInformation[] The Xcode versions available on this device gateway.
appium AppiumInformation[] The Appium versions available on this device gateway.
appiumConfigurationError string Any known configuration issues with the Appium installation.

Data Types

Any data type with a question mark postfix is optional. Generic types are represented with less than greater than brackets. For example, ResultModel<Guid> would be a ResultModel with a data property of Guid.

Guid

All Guids are v4 uuids. Most requests in GigaFox refer to objects internally by an assigned Guid. They should be treated no differently than strings.

Example: 1c32079b-53bc-4bc4-bcf6-71444a7e6bb6

bool
A boolean value.
bool results are always returned as true or false.
Requests accept boolean values in any case.

Examples:

  • True
  • true

String

Text. A sequence of characters.

int

A 32bit signed numerical value. Ranges are -2147483648 to 2147483647.

long

A 64bit signed numerical value. Ranges are -9223372036854775808 to 9223372036854775807.

DateTime

Represents a date and time combined.
DateTime results are always given as fully qualified ISO 8601 combined date time stamps in UTC.

Example: 2016-08-10T08:04:00Z
Requests accept any format which is valid for .net's DateTime.Parse. The timezone is presumed the server's timezone unless specified.

Examples:

  • 05/01/2016 14:57:32.8
  • 2016-05-01 14:57:32.8
  • 2016-05-01T14:57:32.8375298-04:00
  • 5/01/2016

TimeSpan

TimeSpans are returned as the total number of seconds as a decimal.
Example: 550000.0