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:

or if you are using an AD user, like so

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.