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.