The REST API in VMWare Workspace ONE (WS1) is a part of the product rarely talked about and for many is a mystery of what it does and how it can be used. In this blog I want to unwrap some of that mystery and talk about a use case that I recently got involved with where the Rest API provided the perfect solution.
The use case was to be able to plot device data onto Open Layers which is a free map software. Open Layers has advanced modes for providing very granular map data including paths and tracks that is not available on something like Google Maps.
The WS1 platform is capable of logging a device GPS location based on an interval that can be customised. That data is stored and can be displayed in a simple UI in the console showing the point on Bing maps.
The above whilst sufficient to show on an ad hoc basis, doesn’t have the capability to use Open Layers or show all devices on a single map. This is where the REST API can come in and be extremely useful to extend the functionality based on the data WS1 is holding.
VMWare WS1 has an extensive list of powerful APIs that can meet the needs of many use cases. From pushing iOS updates and deleting devices in bulk or in this case retrieving GPS data.
Every environment has an API explorer site to view these APIs- accessible in the format: https://cn1300.awmdm.com/API/help/ There is even the ability to login and try some of these APIs from the Explorer.
Personally I like to use Postman to run and test API calls, its my test bed to run the APIs ad hoc before developing them into a wider solution, so that’s what I will talk though in this blog. Postman is free to us and available online.
There are 4 key pieces of information needed to use the WS1 Rest API, URL of the API, aw-tenant-code, Authorization and Content-Type. The aw-tenant-code is stored at the Customer OG in the WS1 console and is found under Settings>System>Advanced>API>Rest API. The Authorization header needs to be generated from an Admin Username and Password from the correct OG, it’s a encoded string in base-64. Luckily Postman can generate this for you as shown below.
Sample:
URL of the API: https://as137.awmdm.com/api/mdm/devices/extensivesearch
aw-tenant-code: zMj+ul/8tDRG7HVdnOPPxxxxxxxxxxxxxxxxxxxxxxxx
Authorization: Basic TWF0dEFQSTU6TWxxxxxxxxxx
Content-Type: application/json;version=2
If its all working, then pressing ‘Send’ will return some data. I like to use the Json format rather than XML.
Now we have Postman working, we can start to look at the APIs we might need to retrieve GPS data. Using the API Explorer and searching for GPS there are 2 APIs that we could use:
Get- https://as137.awmdm.com/api/mdm/devices/{id}/gps
Post- https://as137.awmdm.com/api/mdm/devices/gps
The Get API works on a per Device Id basis, if we have a list of 100 device IDs then we could call that API 100 times and we would return 100 GPS co-ordinates. However that’s not the most efficient way to do this. The second API uses bulk data, by providing a body to the API with the 100 Device Ids listed it would call a single API and return all the GPS data from the devices.
A common question I get asked is around the Device ID, what is it and how to we get it. The Device ID is as sequential number that WS1 generates every time a device enrols, it is completely separate from the device serial number/UDID etc. You can actually find out the device Id when you view device details in the WS1 console:
For our solution however we would want to call an API which gives us these Device Id. We have a standard, lite and extensive search API which all could do this. As we only have a basic requirement for the search, I will use the standard search API.
Get- https://as137.awmdm.com/api/mdm/devices/search
We now have a solid concept of what it will take to get the GPS co-ordinates for all devices enrolled in the WS1 platform.
- Run the search API and store all the Device IDs that are returned.
- Run the GPS bulk API with a body of all the Device IDs.
- Plot the GPS coordinates returned on a map using OpenLayers.
Im going to create a HTML webpage using Javascript to create the solution and join up all the API calls. I highly recommend using Chrome whilst building/testing and using the inbuilt Chrome Console to monitor the API calls, network/ outputs etc.
After a few hours of building and testing I end up with the start of a viable solution:
I won’t share all my code in the blog, but here is a snippet:
As an extension to the solution I added the ability to click on the GPS points and show a popup with some additional device information which I was storing from the Search API.
Hopefully in this blog you have seen how versatile the Rest API can be, I have worked with many clients using in lots of different ways to meet unique challenges. Recent ones include bulk Device Wipe and Delete of devices and automatically upload Internal APKs.
Im happy to share the entire solution on demand, so reach out if you have any questions!
Pritpal
April 9, 2024Hi Matt, Are you able to share the solution as we are looking to implement something similar.