February 11, 2022

Git Commit(ted) Pro Tips and Tricks - How to be an API Boss

Today we will jump right in and get our first look at using Visual Studio Code, known as VS Code for short. If you followed the first day’s recommendations, you likely already have VS Code, or another code editor downloaded and installed. This blog will leverage VS Code as the code editor, Postman as the API client, and Microsoft Edge based on Chromium, as the browser to leverage Developer Tools (DevTools) to inspect API calls within VMware Workspace ONE UEM. You can choose to leverage your preferred software, but if you are a beginner, I would advise following along with the same software mentioned above.

Today we will jump right in and get our first look at using Visual Studio Code, known as VS Code for short. If you followed the first day’s recommendations, you likely already have VS Code, or another code editor downloaded and installed. This blog will leverage VS Code as the code editor, Postman as the API client, and Microsoft Edge based on Chromium, as the browser to leverage Developer Tools (DevTools) to inspect API calls within VMware Workspace ONE UEM. You can choose to leverage your preferred software, but if you are a beginner, I would advise following along with the same software mentioned above.

Before we Begin

Before we get started, ensure that you have the following:

  • Access to a Workspace ONE UEM Console with Sensors or Scripts enabled with admin access to create or modify existing Sensors or Scripts. You should leverage a test organization group and not leverage a production environment.
  • A Code Editor installed and ready to go. In this blog, we use Visual Studio Code.
  • A REST API Client. In this blog, we use Postman.

Check out the video below that covers everything in this blog and more. We demonstrate how to get started and share some exciting pro tips and tricks more fully than in the blog text.

https://youtu.be/P2kG6ge7rOc

Reverse Engineering API Calls using DevTools

Before I can explain how to reverse engineer or better understand how the API calls work, I have to explain that the Workspace ONE UEM console is undergoing a modernization effort to move from the ASP.NET MVC (Model-View-Controller) framework to using the Angular responsive framework using the Clarity Design System. Overall, it is not possible to capture how the Workspace ONE UEM console leverages the API in the portions of the console that are still using the MVC framework. However, the Angular parts of the console allows us to inspect the network using DevTools to see how the console leverages the REST APIs.

This is not a full-proof method, but I love using this method even before looking at our API documentation to understand the chain of API commands needed to complete specific tasks. You can also quickly find the API endpoint, the required parameters, formatting, and the expected response from calling that API.

You probably want to know which parts of the console are on Angular now. When clicking on a new page in the Workspace ONE UEM console, the best way to tell if the page is Angular is to see a Workspace ONE Loading image during the page reload. You know that the page just went from an MVC page to an Angular page when you see this. Also, a good guideline is that new features or newly added parts of the console are likely on Angular. I primarily work with the Windows platform, so I can share off the top of my head that Baselines, Sensors, Scripts, and Freestyle Orchestrator are on the Angular framework. Today, we will be focusing on Sensors/Scripts for our example.

Workspace ONE loading gif

Figure 1: Workspace ONE UEM Loading Image when Switching to Angular

Inspecting the Sensors/Scripts API Commands using DevTools

 

Graphical user interface, application</p>
<p>Description automatically generated

Figure 2: Sensors List View in the Workspace ONE UEM Console

You can open the DevTools UI in many ways. I will review two methods, but a quick search will tell you how to open DevTools based on your browser and OS platform choice.

  1. Right-click on the webpage, then select Inspect.

Graphical user interface, application</p>
<p>Description automatically generated

Figure 3: Getting to DevTools in Microsoft Edge on macOS

A black screen with white text</p>
<p>Description automatically generated with low confidence

Figure 4: Getting to DevTools in Microsoft Edge on Windows

  1. Leveraging the keyboard shortcut commands. Press F12 or Control+Shift+I (Windows, Linux) or Command+Option+I (macOS).

    Once you have the DevTools UI open, click the Network tab. We can now mimic the actions in the console to further investigate how the API works. Let’s look at how to list all of the Sensors that are in the Workspace ONE UEM console. We also take a look at how to create a new Sensor in this video along with more information on using VS Code.

  2. With DevTools open, refresh the Workspace ONE UEM console to reload the Sensors page. You should start to see a bunch of requests populate while on the Network tab. If you do not see anything, ensure the record icon is clicked to capture network traffic.
  3. You can use the filter/search to narrow down our search. I allows use /api/ when I don’t know any information about the API. To narrow down our search more for this use case, please enter /api/mdm/ since I already know Sensors is part of the MDM APIs.
  4. Click the last request. You should now see the request URL, request method, API-supported-versions, content-type, x-api-version, and so on. Based on this information, we can leverage our API client to learn how to leverage the GET Device Sensors API to return a list of all the Sensors. We can see from the information here that there are two supported versions of this API, and the console is leveraging version 2 (x-api-version is set to v2).
  5. If you click Response, you will see the JSON that is returned with a list of all of the Sensors. You can explore that, but let’s move on to making this call in the Postman client where we can clearly see the response information.

Figure 5: Searching to the Device Sensors API in DevTools

Making REST API Calls using Postman

If you have not already walked through yesterday’s blog, Getting Started using Postman, I highly suggest reading that before continuing to learn the basics of using Postman.

  • Launch Postman and create a new request. You can click on New, then HTTP Request.
  • We are using a GET verb, so no need to change that. Let’s paste in our request URL from DevTools. After pasting the request URL, you should see the Params section auto-populate.
    1. https://ws1beta.airwlab.com/API/mdm/devicesensors/list/5738737c-2ed8-4d26-a1fe-83ddb8a125cf?page_size=20&page=0&orderby=LastModifiedOn&sort_order=DESC&query_type=&platform=
      1. https://ws1beta.airwlab.com is our API console hostname.
      2. /API/mdm/devicesensors/list tells us where to find the documentation for this API. We now know that we are using the v2 MDM APIs for listing the device sensors. The GUID value is the UUID for our organization group. For more information on obtaining this value, refer to the Getting Started with the Workspace ONE UEM APIs blog.
      3. Query Params allow you to narrow the scope of what is returned, including paging. For testing, I usually increase page_size to the number of items I want, such as 103, since I have 103 Sensors in the console. This ensures everything is returned on page 0. However, when using this API in production code, you will want to build paging for efficiency or leverage the other query parameters to narrow the scope.

Figure 6: Creating new HTTP GET Request in Postman

  • We now have to authenticate the API request. We will be using an unconventional shortcut in this blog to save time. If you have already set up Postman from the last blog or know how to properly authenticate using Basic, Certificate, or OAuth, you can skip the following steps. Please keep in mind that this should not be used in production code as this method leverages your active browser session’s authentication. In Postman, select Bearer Token for the Auth Type.
    1. Copy the Bearer token in the Authorization field under Headers > Request Headers. Then paste only the token without “Bearer” into the Token field in Postman.

Graphical user interface</p>
<p>Description automatically generated

Figure 7: Request Headers in Microsoft Edge that will be used in the following steps

Graphical user interface, text, application, email</p>
<p>Description automatically generated

Figure 8: Using Bearer Token to Authenticate the Device Sensor GET Request

  • Lastly, we will want to add the aw-tenant-code and the Accept header. The Workspace ONE UEM APIs require an API key (aw-tenant-code) to be sent for additional authorization. This key is sent in the aw-tenant-code request header. The key can be found on the REST API settings page of the Workspace ONE UEM. This was covered in the previous blogs in this series. Different API versions can be fetched by adding the version details in the Accept header. A single API URL serves the purpose of retrieving multiple versions based on the version details in the Accept header. In our example, we will be using version 2 and will want the response returned in JSON so our Accept header will look like: application/json;version=2.
    1. You can copy the aw-tenant-code and Accept values from Microsoft Edge DevTools to Postman.
    2. Once you have added these headers, you can click Send.
    3. You should see a 200 OK returned. If not, check your URL, Bearer Token, and Request Headers. You should see the same Sensors from the console returned as JSON. You can now see all of the information included for each Sensor. Your next steps would be to repeat this process for getting each Sensor’s details (we cover this in the video), editing Sensors, and deleting the Sensors to fully understand each of the API requests. Pay attention to when GET, PUT, DELETE, or POST are used in Edge.

 

Graphical user interface, text, application, email</p>
<p>Description automatically generated

Figure 9: Postman Request Headers and Sending the GET Device Sensors API Request

This is the first step I take before programmatically leveraging APIs to better understand how the console uses the APIs. You would then want to use a code editor to create the authentication headers, then make the API calls. You can then string the API calls together to automate tasks.

I personally used this exact process for learning how the console uses the Script/Sensor APIs to build a PowerShell script that imports, bulk assigns, bulk deletes, bulk update Sensors in the Workspace ONE UEM Console. You can find sample Sensors and Scripts and the import_sensor_samples.ps1 and import_script_samples.ps1 in the VMware EUC-Samples GitHub repository. You can check out these scripts to see how you would chain the commands together using functions to automate tasks. We will provide more details on this GitHub repository in another blog this month.

Visual Studio Code Overview

VS Code is a lightweight yet powerful code editor which runs on the Windows, macOS, and Linux platforms. It comes with built-in support for JavaScript, TypeScript, and Node.js, and has a rich ecosystem of extensions for other languages (such as C++, C#, Java, Python, PowerShell) and runtimes (such as .NET and Unity). For more introductory information on using VS Code, check out these videos. Ensure you have Visual Studio Code downloaded and installed before continuing.

Installing VS Code Extensions

VS Code has a rich ecosystem of extensions for other languages, tools, and runtimes. We mentioned the Thunder Client extension in the first blog of this series. Today we will be exploring other helpful extensions to make formatting and transforming data quick and easy.

To install extensions, you can either search the Visual Studio Marketplace by navigating to https://marketplace.visualstudio.com/vscode or searching the Marketplace directly in VS Code.

A screenshot of a computer</p>
<p>Description automatically generated with low confidence

Using VS Code Extensions to Quickly Format & Transform Data

We will simply list the various extensions we covered in the video at the start of this blog, but won’t go into all of the details. To see these extensions in action, watch the video. We also show you how to use these extensions to decode the Sensors Base64 encoded data then re-encode, which is needed when leveraging these APIs to modify or create new Sensors or Scripts.

The video covers these extensions:

  • XML Tools used for formatting XML, XQuery, and XPath Tools
  • vscode-base64 used for encoding and decoding Base64 data
  • JSON Tools used for manipulating, formatting, and minifying JSON

Key Learnings & What’s Next

Today, we explored how to leverage your browser’s DevTools UI to examine how the Workspace ONE UEM Console leverages the Workspace ONE UEM REST APIs. This method is for quickly seeing a working example of the APIs and should not replace leveraging the Workspace ONE UEM API Documentation site. We leverage Postman to make a GET request to return a list of the device Sensors in our console, then leveraged VS Code extensions to learn how to quickly modify data such as XML, JSON, and Base64 encoding and decoding. Check out the video to see everything covered in action and how to make the additional API calls to create new Sensors!

Be sure to subscribe to the Digital Workspace Tech Zone Blog RSS or check back daily to see what we release. By the end of this month, we hope that you are comfortable leveraging code samples, VMware Flings, scripting/coding, and leveraging the EUC APIs to automate your workspace!

You can also follow us on Twitter @EUCTechZone to stay updated on the latest EUC content!

Agenda

Make sure to check out the other blog posts in our 28-day series:

 

Filter Tags

Horizon Workspace ONE Workspace ONE Access Workspace ONE Intelligence Workspace ONE UEM Blog Technical Overview Intermediate Optimize