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.

Authorization

Mason API requires a client to use a basic access authentication method when making a request.

  • A request needs to contain a header field in the form of authorization: basic $APIKEY

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. For more information visit the Device Model page.

{
  "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