UEM Getting started with REST

BlackBerry UEM is the first release of our core EMM solution to include public REST APIs. For legacy BES users,
BWS (BlackBerry Web Services) was the sole API for programmatically invoking actions on BES and was built on
legacy SOAP calls. Good Control, the core EMM Good solution similarly had a collection of SOAP calls, but at the
time of its purchase by BlackBerry was already starting down the path of REST API’s. With the release of UEM,
REST now takes prominence as the future of API calls from the legacy of both previous products.
Why REST? Primarily two reasons. First, performance. REST calls are tight, minimal JSON objects compared to
the broad, rather descriptive calls that SOAP requires. Not particularly friendly to mobile communications given the
slower speeds and bandwidths available to mobile users. 2) its JSON, and its 2017. Developers frequently use
JSON objects as there default payload whether in web development or native apps. Developers expect to see
JSON, not xml. So, as part of the migration from BES/GC to UEM, REST, full speed ahead.
What’s available in the first launch?
• REST API’s use the same port and authentication scheme the older BWS interface (port 18084).
• EMM functions provided by Good Control have been ported to UEM as REST calls
• The initial launch of REST API’s is a short list, but will be growing on each release as we update older calls
from SOAP to REST.
• As new features are added to UEM, you can expect access to them as new REST API’s.
• Note: BWS calls that were in BES12.5 are STILL there, and will remain unchanged.
For more info, check the release notes for UEM: http://help.blackberry.com/en/blackberry-uem/12.6/release-notes-
and-advisories/iju1484768858105.html
How to get started…
There are many ways to invoke a REST API, commonly, you can build your own (Java, .Net, Javascript, etc.) The
online doc’s show samples using the command line tool CURL, but I prefer using a nice UI. I recommend using a
modern UI based tool, in this case, I recommend Postman (https://www.getpostman.com/apps )
You will also need access to a UEM server https://global.blackberry.com/en/enterprise/blackberry-uem.html
To test your connection try it with “ping”. There 2 versions of ping available, one authenticated, and one without.
Let’s try it without authentication first:
Your URL will look like this:
https://myserverURL:18084/tenantGuid/api/v1/util/ping
where
• myserverURL is the URL to your UEM server,
• 18084 is the default port that REST API calls are made with.
• tenantGuid is the identifier you used when registering your UEM server, also known as the SRPID.
The request doesn’t require authentication and should return a plain text string with uptime like so:

You might notice, that this would just as easily have worked in a browser:
Most REST calls however, require authentication. Like “ping” there is an “authorization” call.
Your URL will look like this:
https://myserverURL:18084/tenantGuid/api/v1/util/authorization
It requires a header with content type like so:
Key=”Content-Type” value=”application/vnd.blackberry.authorizationrequest-v1+json”
This request is going to be a “POST” not a “GET”. In the body of the “POST” place the following:
1 {
2 "provider" : "LOCAL",
3 "username" : "edbourne",
4 "password" : "cGFzc3dvcmQ="
5 }
or if you are using an AD user, like so
1 {
2 "username" : "edbourne",
3 "password" : "cGFzc3dvcmQ=",
4 "domain" : "example.com",
5 "provider" : "AD"
6 }
Where the value of password is base64 encoded. This is a bit of a pain. There is no base64 encode command built
into Windows (what I’m using). Search for a solution, there are lots, but, if you’re a fan of Notepad++, it does
include this as a feature. Simply type in your password (I’m literally using password), highlight it, right click on it,
choose plugin commands, Base64 Encode, like so:
Copy and paste the result into the field above.
Here it is with the body displayed:

Here it is with the Headers displayed:

And after you press send with your POST you should see the authorization string you will need:
You are now ready to try the authenticated ping from earlier.
Your URL will look like this:
https://myserverURL:18084/tenantGuid/api/v1/ping
What is the difference? This is no /util in the string. The util apis of authorization and ping, do not require
authentication, while all other API’s do.
Add a header, with key = Authorization, and value= the string you generated above in the authorization call.
Press send, and you will get the same up and running result as previously.
Here is a more complex example, this time using
https://myserverURL:18084/tenantGuid/api/v1/directories/users
and I’m going to add the options of searching for myself, and including existing users = true.
https://myserverURL:18084/tenantGuid/api/v1/directories/users?search=bourne&includeExistingUsers=true
and of course, I add in a header with the authorization key and value pair from above.
The result looks like this:
Try the other REST API’s in Postman, or whatever tool or language you prefer.
In part one I covered the basics of getting REST APIs authenticated and returning results with UEM. With each new
release of BlackBerry UEM, we have added significant new REST APIs to the mix. So, it’s time to highlight some of
the new calls and new options available. Here are my thoughts:
User management was mature in the older BWS (on BES) and GC/CAP SOAP calls (from the legacy Good
servers). But SOAP is not REST. With the launch of REST in 12.6 and the updates in 12.7 the REST APIs are
quickly catching up. Here are some highlights from the latest UEM 12.7 release that I suggest having a look at:
For those interested in User management related APIs (perhaps your company likes to build out its own self-service
front end), new choices for a user account include:
deleting
changing the password
adding and removing from a group
check devices assigned
certificate management
We also added pagination support when returning results, for those of you with large user lists. Closely related
Group management now comes with support for create and delete of a user group, assigning applications, and
querying who is a member of a group.
We have had feedback from many Development partners looking for additional device related APIs. So, we have
added a new device search. You can search by IMEI, MEID, UDID, GUID of the device (a BlackBerry specific
key, we assign) and WIFI MAC address. We return lots of detail including device activation type, compliance state,
OS Family Name, ownership information and more.
Ie:

GET /{tenantGuid}/api/v1/devices
{
"devices": [ {
"links" : [ {
"rel" : "userDevice",
"href" : "https://server01:18084/SRP00000/api/v1/users/6dd3a8e2-3f24-48c6-961a-
949794f4b554/userDevices/2d2d3a7f-076d-46f9-8c25-56cb8eba2800"
 } ],
"guid": "4659aa7f-0a7d-9f69-258c-2800ebaa2800",
"activationDate": "2017-01-16T14:47:03.662Z",
"activeSyncId": "K6CKULJTID3SDEAIV0ELHBBTTO",
"batteryLevel": 95.0,
"compromised": false,
"externalStorageFree": 12021.0,
"externalStorageSize": 16386.0,
"hardwareModel": "Desire",
"hardwareName": "bravo",
"homeCarrier": "Rogers",
"internalStorageFree": 2112.0,
"internalStorageSize": 32768.0,
"imei": "990000862471854",
"os": "Android 5.0",
"osFamilyName": "android",
"osVersion": "5.0",
"ownership": "PERSONAL",
"phoneNumber": "4045551234",
"serialNumber": "c08088415436112",
"udid": "d88496fdf7115ac9f3ab69966cbaf91d960b95036fa68f66489c8ad78f136b5c",
"wifiMacAddress": "62:9a:7e:bc:fe:01"
} ]
}

One key change coming with UEM 12.7 MR2 is to help developers looking for a list of installed applications on
device, particularly on iOS. With the release of iOS 11, access to this information is blocked for 3rd party
developers. However, if your iOS device is managed by the UEM server, starting with UEM 12.7.2 you will be able
to do the following:
GET /{tenantGuid}/api/v1/users/{userGuid}/userDevices/{userDeviceGuid}/applications
{
"deviceApplications": [
 {
"guid": "3304ab07-e595-494e-a08a-63eedb9a62e5",
"bundleId": "com.blackberry.gd.tasks",
"disposition": "OPTIONAL",
"dynamicsContainerId": "25A64379-25A1-42AB-8104-3B41F98B260A",
"status": "ACTIVATED",
"name": "BlackBerry Tasks",
"personal": false
},
{
"guid": "3980996d-6741-44c8-9703-a4ed2930fcc5",
"bundleId": "com.good.gcs",
"disposition": "REQUIRED",
"dynamicsContainerId": "C85ECFF5-A3DB-4FDC-887F-8712220EBD92",
"status": "ACTIVATED",
"name": "BlackBerry Work",
"personal": false
},
{
"guid": "80cf4d96-b230-45a7-ad21-77bb5cfba35c",
"bundleId": "com.blackberry.gd.notes",
"disposition": "OPTIONAL",
"status": "NOT_ACTIVATED",
"name": "BlackBerry Notes",
"personal": false
}
]
}

Results will show up similarly for those of you working with Android devices.
So, go out there and try UEM 12.7 REST APIs. Let me know what you think in the comments below, or on the
community forums.
About Ed Bourne
Ed Bourne brings over 10 years of experience in mobility as a Sr. Enterprise Solutions Manager at BlackBerry. Ed
manages the technical partnerships with some of our largest Strategic Partners and Customers, helping to foster
BlackBerry expertise and bring a compelling mobile experience to our joint customers.