Introduction to Mason API

The Mason API is a series of REST routes that enable customers to perform operations against their fleet of devices using common internet standards of HTTP and OAuth.

Terminology

  • Mason API is a set of REST endpoints to access the Mason platform.
  • API key is a secret used to access the API. It can be scoped down lower than admin.
  • Scope is set on an API key to specify what permissions it should have.
  • Fleet is a boundary for set of devices and groups. Currently, we only support the default fleet.
  • Group is way to group devices and specify how to configure them.
  • Device is an actual Mason device such as a phone.

API KEYS

With the Mason API, we will be introducing API Keys which are non-expiring authentication tokens. These tokens are presented as one-time secrets which customers can manage to give their applications only the permissions that they need.

With the initial release of the API, there are two scopes:

  • FLEET:READ limits API access to only non-state affecting GET operations such as reading all the devices and groups within your fleet.
  • FLEET:ADMIN is an unlimited scope for all operations concerning your fleet. This will allow you ping devices as well as manage the live-time of your device groups. In the future, FLEET:ADMIN will also allow for rebooting, wiping, and refurbishing devices.

URL Format

The API Mason URL will be:

https://api.bymason.com/{version}/{fleet_name}

  • version initially V1 represents the version of the API to use.
  • fleet_name indicates which device fleet to use. Currently only default is supported.

Enumeration

Our list APIs include paging by default. Responses to list APIs will include identifers that can be used to walk back and forth between pages.

{
  "data" = { ... }, // The data that you were expecting
  "prevPage" = "before_identifer",  // Optional this is populated when requesting data that can be paged
  "nextPage" = "after_identifier"    // Optional this is populated when requesting data that can be paged
}

In order to specify which page you are interested in, we use common parameters:

Parameters Description Example
limit Limit to number of devices returned /v1/default/device?limit=10
before Request the previous page /v1/default/device?before=beforeIndex
after Request the next page /v1/default/device?after=afterIndex

Devices

Device Response

The Device Response JSON is intended allow for a rich ability to use the information about a device for a variety of purposes. We include information from the latest device heartbeat such as battery level, and the applications currently on the machine.

You can use the /refresh api to update this data with the newest information on the device.

{
  "apps": [
    {
      "name": "company.division.application1",
      "version": "12345"
    },
    {
      "name": "company.division.application2",
      "version": "2454"
    }
  ],
  "battery": {
    "level": "81"
  },
  "connection": {
    "dataUsage": {
        "appsDataUsage": [
            {
                "packageNames": [
                    "com.myexample.app3"
                ],
                "uid": 10083,
                "usageCycles": [
                    {
                        "startTime": "2019-11-02T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 484725,
                                "bytesSent": 46580
                            }
                        ]
                    },
                    {
                        "startTime": "2019-12-01T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 0,
                                "bytesSent": 0
                            }
                        ]
                    }
                ]
            },
            {
                "packageNames": [
                    "org.example.app1"
                ],
                "uid": 10082,
                "usageCycles": [
                    {
                        "startTime": "2019-11-02T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 5138957,
                                "bytesSent": 337008
                            }
                        ]
                    },
                    {
                        "startTime": "2019-12-01T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 13357,
                                "bytesSent": 3925
                            }
                        ]
                    }
                ]
            },
            {
                "packageNames": [
                    "system"
                ],
                "uid": 1000,
                "usageCycles": [
                    {
                        "startTime": "2019-11-02T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 81689926,
                                "bytesSent": 5423191
                            }
                        ]
                    },
                    {
                        "startTime": "2019-12-01T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 245133,
                                "bytesSent": 64784
                            }
                        ]
                    }
                ]
            }
        ],
        "usageCycles": [
            {
                "startTime": "2019-10-26T08:16:55Z",
                "endTime": "2019-11-25T08:16:55Z",
                "usages": [
                    {
                        "type": "wifi",
                        "bytesReceived": 4278806,
                        "bytesSent": 4340376
                    }
                ]
            },
            {
                "startTime": "2019-11-24T08:16:55Z",
                "endTime": "2019-11-25T08:16:55Z",
                "usages": [
                    {
                        "type": "wifi",
                        "bytesReceived": 1029194,
                        "bytesSent": 1185728
                    }
                ]
            }
        ]
    },
    "bluetooth": {
        "enabled": false,
        "macAddress": "",
        "name": "",
        "pairedDevices": null
    },
    "sim": [
      {
        "carrier": "No service.",
        "countryiso": "us",
        "iccid": "6367377378783365457",
        "mcc": "420",
        "mnc": "525"
      },
      {
        "carrier": "No service.",
        "countryiso": "us",
        "iccid": "6367377378783365457",
        "mcc": "420",
        "mnc": "525"
      }
    ],
    "wifi": {
      "adapterMacAddress": "12:00:00:00:00:0",
      "bssid": "e0:ab:47:be:f6:c0",
      "enabled": true,
      "ipAddress": "172.20.8.174",
      "ssid": "\"BrandX_WiFi\""
    }
  },
  "createdAt": "1516239022",
  "family": "D450",
  "group": {
    "name": "Test Group",
    "self": "/v1/default/group/8989-3535-3233"
  },
  "id": "Praesentium expedita quo earum temporibus praesentium aut.",
  "imei": "359333090374045",
  "name": "TestDevice001",
  "os": {
    "configuration": {
      "device": "E81",
      "product": "default",
      "project": "myapplication",
      "version": "2"
    },
    "masonOS": {
      "incremental": "NX08351F",
      "release": "1.2.3"
    }
  },
  "status": {
    "op_updated": true,
    "apps_updated": true,
    "project_updated": true
  },
  "self": "/v1/default/device/40052b21-211c-4d1e-9e81-fec7e2f64582",
  "serialnumber": "40052b21-211c-4d1e-9e81-fec7e2f64582",
  "lastcheckin": "2019-06-26T15:47:42.269Z"
}

Device APIs

Scope FLEET:READ

GET /v1/default/device

Enumerate a page of devices

Parameters Description Example
name Lookup a device by its name /v1/default?device?name=TestDevice001
limit Limit to number of devices returned /v1/default/device?limit=10
before Request the previous page /v1/default/device?before=40052b21-211c-4d1e-9e81-fec7e2f64582
after Request the next page /v1/default/device?after=40052b21-211c-4d1e-9e81-fec7e2f64582

GET /v1/default/device/{id}

Requestion information for a unique device

GET /v1/default/device/{id}/ping

Send a non-intrusive ping to the device. This will check if it is connected to the server without interacting with the device directly.

POST /v1/default/device/ping

Send a non-intrusive ping to the many devices at once. This will check if it is connected to the server without interacting with the device directly.

Request Body

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ]
}

Scope FLEET:ADMIN

POST /v1/default/device/{id}

Rename a device

Request Body

{
    "name": "Device001"
}

POST /v1/default/device/broadcast

Send an Android broadcast to an application on your device.

Request Body

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ],
    "targetApps": ["com.example.myapplication"],
    "command": "YOUR_COMMAND_HERE",
    "args": ["arg1", "arg2"]
}

Note: You can use either the UUID or the Self property from the device JSON.

POST /v1/default/device/refresh

Send a refresh message a list of devices

Request Body

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ]
}

Note: You can use either the UUID or the Self property from the device JSON.

POST /v1/default/device/update

Send a message to a list of devices to check for updates.

Request Body

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ]
}

Note: You can use either the UUID or the Self property from the device JSON.

POST /v1/default/device/reboot

Send a reboot message a list of devices

Request Body

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ]
}

Note: You can use either the UUID or the Self property from the device JSON.

POST /v1/default/device/shutdown

Send a shutdown message a list of devices

Request Body

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ]
}

Note: You can use either the UUID or the Self property from the device JSON.

POST /v1/default/device/wipe

Send a message to a list of devices to wipe themselves back to factory reset.

Request Body

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ]
}

Note: You can use either the UUID or the Self property from the device JSON.

Groups

Group Response

The JSON for a group includes when it was created, the user defined description and names, as well as a self reference to easily call back to the API.

{
    "createdAt": "2019-04-15T21:14:31.369Z",
    "description": "This is a test group.",
    "name": "Test Group",
    "self": "/v1/default/group/Test%20Group"
}

Scope FLEET:READ

GET /v1/default/group

Get a page groups in the fleet.

Parameters Description Example
limit Limit to number of devices returned /v1/default/group?limit=10
before Request the previous page /v1/default/group?before=40052b21-211c-4d1e-9e81-fec7e2f64582
after Request the next page /v1/default/group?after=40052b21-211c-4d1e-9e81-fec7e2f64582

GET /v1/default/group/{name}

Get a specific group

GET /v1/default/group/{name}/list

Get the list of devices that are part of group

GET /v1/default/group/{name}/deployment

Get the list of deployments that have been published to this group

Scope FLEET:ADMIN

POST /v1/default/group

Create a new group and optionally move devices into that group.

Request Body

{
    "description": "Description of my group",
    "name": "TestGroup"
}

POST /v1/default/group/{name}/move

Parameters Description Example
validateonly Validate if the move is allowed /v1/default/group?validateonly=true

Update an existing group and/or move devices into it.

Request Body

Note: You can use either the UUID or the Self property from the device JSON.

{
    "devices": [
        "40052b21-211c-4d1e-9e81-fec7e2f64582",
        "40052b21-211c-4d1e-9e81-fec7e2f64583"
    ]
}

DELETE /v1/default/group/{name}

Delete an empty group

Note: Deleting a non-empty group return a 403 FORBIDDEN

Errors

Error JSON

For responses other than 200, the following format is expected:

{
  "type": <error_type_category>,
  "message": <error_message>
}

Example:

{
  "type": "authentication_error",
  "message": ""Required authorization token not found"
}

HTTP Status Code

The Mason API will return the following status codes

Code Description
200 - OK Everything worked as expected.
400 - Bad Request,The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
403 - Forbidden The authorization token does not allow the requested action.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Internal Server Errors Something went wrong on Mason's end. (These are rare.)

SPEC REVISIONS

Changes in 1.0.1

  • Change the example for /v1/default/group/{name}/move and /v1/default/device/Refresh to indicate that you can just use UUID or Self (with UUID being the example).

Changes in 1.0.2

  • Added reboot and shutdown endpoints
  • Enumeration response paging changed to prevpage and nextpage