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
andnextpage