Mobile Data Anywhere - API Reference

This is the documentation for the Mobile Data Anywhere API.

All requests are made over HTTPS. All requests require authentication, except asking the server what the time is using the GET /api/v1/time method.

Authentication

Each request is individually authenticated without the use of cookies. Authentication requires the following HTTP headers to be defined for each request:

  • HTTP-X-API-TIMESTAMP: This is the unix time stamp of when the client makes the requests. Unix timestamps measure the elapsed time in seconds since 1 January 1970 in UTC to the current time in UTC.
  • HTTP-AUTHORIZATION: each request is authenticated using basic HTTP authentication as follows:
    • Username: This is the same as the user name that is used to log in to the Mobile Data Anywhere site.
    • Password: This is a calculated value that is unique for each request. It is calculated based on the following formula (pseudo-code):

password = Base64-encoded( HMAC-SHA256( "name:" + username + ";timestamp:" + timestamp + ";", api_secret ) )

Where the first argument to the HMAC-SHA256 function is the document to be hashed, and the second argument is the HMAC “secret”.

The timestamp must be exactly the same as the value given in the header, and must be within a close enough margin to the time in the server. This mitigates against replay attacks.

Requests that do not pass authentication will return a 403 Forbidden error status.

Example authentication

Given the following:

timestamp = 123456789
username = "username"
api-secret = "some-api-secret"

Then the calculated password would be:

"gFUxSuDp1AexwedepvxGPOixhk4jsiinClqYGrjqkNc="

JSON Responses

Where an API call returns a JSON response (virtually all calls except those that retrieve raw files or images) the response will conform to the following:

  • The response will be a JSON object (dictionary) with the following keys:

    • "status" (always present) - This will be a string representation mirroring the HTTP response status code, such as success, forbidden, not found or bad request

    • "result" (mostly present) - This will be the result of the API call. For example, count calls will return an integer value in this key. Get List actions will return an array of objects, and get object actions will return a single object here for the response.

    • "message" (sometimes present) - An additional human readable status message. Mostly this occurs when there is an error and the message will provide more information on the error. For example, a request missing a required parameter will return a message here indicating why it was a bad request.

Example responses:

  • GET /api/v1/devices/count -> {"status":"success","result":1}

  • GET /api/v1/devices -> {"status":"success","result":[{"name":"My iPhone","unit_id":"iphone"},{"name":"My Nexus","unit_id":"nexus"}]}

Request bodies for POST and PUT requests

The API server will accept post bodies as either form encoded data or JSON data, so long as the Content-Type header correctly identifies the content type.

The following request bodies are equivalent:

POST /api/v1/projects/5/deliver
Content-Type: application/x-www-form-urlencoded

unit_id=device-01

And:

POST /api/v1/projects/5/deliver
Content-Type: application/json

{"unit_id":"device_01"}

Time stamps

All server times are stored in UTC.

Where data is recorded in a local time zone (for example, the date created in a session from a mobile client) the time is converted to UTC when the session is received according to the time zone offset recorded by the device if provided, or the default time zone offset for the account to which the device belongs.

All times referenced in the API are in UTC and are typically measured as unix timestamps. That is, seconds since 1-Jan-1970 UTC.

Some API calls will return a date as a string with a timestamp in an adjacent field. The string value is for convenience. The timestamp values are the actual values stored in the system.

Resources

Attachments

Resource Description
Attachments Overview An overview of the Attachments API implementation.
GET /api/v1/project/:project_id/sessions/:session_id/attachments/:id Fetch the raw data of a file attached to a session
PUT /api/v1/project/:project_id/sessions/:session_id/attachments/:id Upload a new file and store it as an attachment to a session
DELETE /api/v1/project/:project_id/sessions/:session_id/attachments/:id Delete an attached file from a session

Dashboards

Resource Description
Dashboards Overview An overview of the Dashboards API implementation.
GET /api/v1/dashboards/:id Get the details for a specific dashboard.
GET /api/v1/dashboards Return a list of all dashbords in the user's account
POST /api/v1/dashboards Save a new dashboard.
PUT /api/v1/dashboards Update an existing dashboard .
DELETE /api/v1/dashboards/:id Remove a dashboard from your account
GET /api/v1/dashboards/:id Remove a dashboard from your account

Devices

Resource Description
Devices Overview An overview of the Devices API implementation.
GET /api/v1/devices List devices in the user's account.
GET /api/v1/devices/:id Get the details for a device.
GET /api/v1/devices/count Return the count of devices in the user's account
POST /api/v1/devices Create a new device in this account
PUT /api/v1/device/:id Update a device in this account
DELETE /api/v1/devices/:id Remove a device from this account
GET /api/v1/devices/:device_id/projects Return a list of projects linked to this device.
POST /api/v1/devices/:device_id/projects/link Link one of more projects to a device
DELETE /api/v1/devices/:device_id/projects/unlink Unlink one or more projects from a device.
GET /api/v1/devices/:device_id/projects/count Return a count of projects linked to this device.

Project ppcx files

Resource Description
Project ppcx files Overview An overview of the Project ppcx files API implementation.

Project web hook events

Resource Description
Project web hook events Overview An overview of the Project web hook events API implementation.
GET /api/v1/projects/:project_id/web_hook/events/:event_id Gets the Web Hook Event, including current state of the event and response code if the event is complete.

Project web hooks

Resource Description
Project web hooks Overview An overview of the Project web hooks API implementation.
GET /api/v1/projects/:project_id/web_hook Get the project's web hook details.
PUT /api/v1/projects/:project_id/web_hook Creates or updates the web hook for a project
DELETE /api/v1/projects/:project_id/web_hook Removes the web hook configuration for the project
POST /api/v1/projects/:project_id/web_hook/trigger_session_test Tests the execution of the project's web hook with a payload containing dummy data with the event type 'session.test'.

Projects

Resource Description
Projects Overview An overview of the Projects API implementation.
GET /api/v1/projects Return a list of all projects in the user's account
GET /api/v1/projects/:id Get the details for a specific project.
GET /api/v1/projects/count Return the number of projects in a user's account
POST /api/v1/projects Create a new project by uploading a .ppc or .ppcx file
PUT /api/v1/projects Update an existing project by uploading a .ppc or .ppcx file
POST /api/v1/projects/:id/deliver Send the project a device
GET /api/v1/projects/:id/devices Return a list of devices linked to this project
POST /api/v1/projects/:project_id/devices/link Link a project to one or more devices
POST /api/v1/projects/:project_id/devices/link_all Link a project to all devices
POST /api/v1/projects/:project_id/devices/redeploy_all Re-deploy a project to all devices
DELETE /api/v1/projects/:id/devices/unlink Unlink one or more devices from a project.
DELETE /api/v1/projects/:id/devices/unlink_all_devices Unlink all devices from a project.
POST /api/v1/projects/:project_id/archive Moves a project from Active to Archived.
POST /api/v1/projects/:project_id/unarchive Moves a project from Archived to Active.

Queued actions

Resource Description
Queued actions Overview An overview of the Queued actions API implementation.
GET /api/v1/queued_actions Return a list of queued actions for a device

Reports

Resource Description
Reports Overview An overview of the Reports API implementation.
GET /api/v1/reports/:id Get the details for a specific report.
GET /api/v1/reports Return a list of all dashbords in the user's account
POST /api/v1/reports Save a new report.
PUT /api/v1/reports Update an existing report .
DELETE /api/v1/reports/:id Remove a report from your account
GET /api/v1/reports/:id Remove a report from your account

Sessions

Resource Description
Sessions Overview An overview of the Sessions API implementation.
GET /api/v1/projects/:project_id/sessions Return a list of sessions in a project
GET /api/v1/projects/:project_id/sessions/count Return the count of sessions in a project
GET /api/v1/projects/:project_id/sessions/:id Fetch the details of a session
POST /api/v1/projects/:project_id/sessions Create a new session in the database.
PUT /api/v1/projects/:project_id/sessions/:session_id Update an existing session.
DELETE /api/v1/projects/:project_id/session/:id Delete a session from the database
POST /api/v1/projects/:project_id/sessions/:session_id/deliver Send this session to a device

Time

Resource Description
Time Overview An overview of the Time API implementation.
GET /api/v1/time Get the current time according to the server.

Ultradrop files

Resource Description
Ultradrop files Overview An overview of the Ultradrop files API implementation.
GET /api/v1/ultradrop_files Returns a list of ultradrop files that have been uploaded to the user's account.
GET /api/v1/ultradrop_files/available Returns a list of ultradrop files that are associated with projects in the user's account.
GET /api/v1/ultradrop_files/count Returns the number of ultradrop files that have been uploaded.
GET /api/v1/ultradrop_files/:id Returns a hash of attributes for the ultradrop file
GET /api/v1/ultradrop_files/:id/download Download the content of the ultradrop file using the file's id
GET /api/v1/ultradrop_files/download?filename=:filename Download the content of the ultradrop file using the filename
PUT /api/v1/ultradrop_files/upload?filename=:filename Upload a new .txt file for an available ultradrop file
DELETE /api/v1/ultradrop_files/:id Delete an ultradrop file from the database