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": {
    "bluetooth": {
      "enabled": false
    },
    "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"
    }
  },
  "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

Scope `FLEET:ADMIN`

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/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.

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

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

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

Introduction to Mason API

Terminology

API KEYS

URL Format

Enumeration

Devices

Device Response

Device APIs

Scope FLEET:READ

Scope FLEET:ADMIN

Groups

Group Response

Scope FLEET:READ

Scope FLEET:ADMIN

Errors

Error JSON

HTTP Status Code

SPEC REVISIONS

Changes in 1.0.1

Changes in 1.0.2

Scope `FLEET:READ`

Scope `FLEET:ADMIN`

Scope `FLEET:READ`

Scope `FLEET:ADMIN`