Device Registry APIs
- Robert Dare
- Jonathan Alaimo (Unlicensed)
Introduction
The Device Registry exposes details about fielded devices via a REST API. The API returns all devices (Blufis and Beacons). Not all fields in each device are meaningful for each device type. Fields not relevant for a given device type will be null.
The Device Registry API supports various query parameters to help narrow a selection. By default, all devices are returned. The "deviceType" parameter can be set to either BLUFI or BEACON. If some unsupported value is supplied, the system defaults to ALL. The system will ignore the "uuid", "major" and "minor" parameters when searching for BLUFI types. Also, if any "uuid", "major" or "minor" parameters are supplied while searching for ALL device types, then only supported device types (in this case Beacons) will be filtered.
Query Parameters
NOTE: The wild card character for search is the percent symbol "%". All queries must be URL encoded, so if the % character is included, it must be encoded as "%25" instead of just "%".
| Name | Required | Default | Description |
|---|---|---|---|
| deviceType | No | % | Set to either "BEACON" or "BLUFI" (case insensitive) - any other value will default to % (ALL) |
| uuid | No | % | Specify a literal UUID value or fragment by using wild card characters % |
| major | No | % | Specify a literal Major value or fragment by using wild card characters % |
| minor | No | % | Specify a literal Minor value or fragment by using wild card characters % |
| name | No | % | The device name |
| deviceId | No | % | The unique record locator id (primary key) of the device |
| mac | No | % | The device MAC ADDRESS |
Example Query String
/portal/papis/v1/projects/<projectId>/registry/devices?deviceType=BEACON&uuid=A6702217-BDC4-45F4-8198-9B7A6E979AB3&major=1200&minor=44797
Fields
The following fields are returned in the API:
| Name | Data Type | Nullable | Device Type | Description |
|---|---|---|---|---|
| id64 | String | No | ALL | The Bluvision unique hardware identifier. |
| macAddress | String | No | ALL | Media Access Control Address. |
| deviceId | String | No | ALL | Unique record locator of device. For Blufi, this is synonymous with "adapterId". For beacons, this is usually the same as the "id64" value. |
| name | String | Yes | ALL | Friendly name assigned by administrator. |
| status | String | No | ALL | The Bluzone Cloud status of the device. |
| deviceType | String | No | ALL | One of BLUFI or BEACON. |
| firmwareType | String | No | ALL | Type of firmware currently installed. |
| firmwareVersion | String | No | ALL | Version of firmware currently installed. |
| latitude | Number | Yes | ALL | Geographic latitude value in decimal format. |
| longitude | Number | Yes | ALL | Geographic longitude value in decimal format. |
| floorNumber | Number | Yes | ALL | The floor number. |
| metaData | JSON | Yes | ALL | Meta-data structure assigned by the administrator. |
| uuid | String | Yes | BEACON | The iBeacon UUID value. |
| major | Number | Yes | BEACON | The iBeacon Major value. |
| minor | Number | Yes | BEACON | The iBeacon Minor value. |
| tags | Array | Yes | ALL | A list of tag names that are associated with the given device in the Bluzone Cloud. |
| eddystoneUidNamespace | String | Yes | BEACON | The Eddystone UID Namespace value |
| eddystoneUidInstance | String | Yes | BEACON | The Eddystone UID Instance value |
| dateCreated | String | No | ALL | Timestamp of when this record was created. |
| dateUpdated | String | No | ALL | Last modified timestamp for this record. |
API
Get Device Registry
Returns a JSON Array of Device objects.
REQUEST
GET https://<host>/portal/papis/v1/projects/<projectId>/registry/devices Accept: application/json BZID: bad18eba1ff45jk7858b8ae88a77fa30
RESPONSE
HTTP/1.x 200 OK
Content-Type: application/json
[
{
"id64": "16179664999283123558",
"macAddress": "01:ed:43:48:4e:1a:86",
"deviceId": "16179664999283123558",
"name": "Concierge Waypoint 3",
"status": "PENDING_UPDATE",
"deviceType": "BEACON",
"firmwareType": "iBeek(Ti)",
"firmwareVersion": null,
"latitude": 26.06289226658518,
"longitude": -80.1861864781028,
"floorNumber": 2,
"metaData": {
"beaconType": "CheckinDesk",
"terminal": "D",
"concourse": "1",
"airside": false,
"publicBeacon": true
},
"uuid": "b2f4ce54-3060-4fb7-97c2-b6fbb2d3c260",
"major": 2100,
"minor": 1228,
"eddystoneUidNamespace": null,
"eddystoneUidInstance": "9B6E1A3F71AA",
"dateCreated": "2015-04-29",
"dateUpdated": "2015-08-25"
},
{
"id64": "3417654221413133211",
"macAddress": "5c:31:3e:04:59:09",
"deviceId": "93721",
"name": "Front Desk: Reception",
"status": "CONNECTED",
"deviceType": "BLUFI",
"firmwareType": "Blufi",
"firmwareVersion": null,
"latitude": 26.06289226658518,
"longitude": -80.1861864781028,
"floorNumber": 1,
"metaData": null,
"uuid": null,
"major": null,
"minor": null,
"tags": ["Blufi", "Test Device"],
"eddystoneUidNamespace": null,
"eddystoneUidInstance": null,
"dateCreated": "2015-08-04",
"dateUpdated": "2015-08-23"
}
]