Introduction to using Postman - Part 1

So, you read about all those fancy APIs for UEM, Access, and UAG and want to start testing them against your Workspace ONE stack, but you don’t want to directly start scripting every request in the language of your choice? There are many tools used by API developers to test and check functional requirements of services, and one of the most popular ones to organize your tests is Postman.

What can I do with Postman?

As you can guess, the main use case of Postman is to test and validate REST APIs using a graphical interface to configure and store your requests. Further, it allows you to run tests on the return values of your HTTP requests helped by Postman’s JavaScript-based language to automate interaction with the data. We will explore how to do your first steps in Postman and show you the best practice of using it with Workspace ONE APIs.

How to get started

Here’s the step-by-step process for installing and using Postman.

Step 1: Access Postman

First, find out more about Postman and how to install and use it: https://learning.postman.com/docs/getting-started/installation-and-updates/
You can either access Postman on the web at https://go.postman.co/home or install it on your platform of choice as a separate app. You will need to create a free account to save your configurations and access them from different machines.

Figure 1: Getting started

Step 2: Set Up Workspace

From the Overview page, you want to jump to the Workspace tab and either use the default “My Workspace,” or create a specific workspace for a project, as in this case for the introduction.

Figure 2: Welcome page

Figure 3: Create workspace

Unless you work in a team or are working on some open-source requests, mark the new workspace as Personal and ignore the other options.

Figure 4: Create workspace 2

Inside your Workspace, you are greeted by an overview and a menu with the main functions of Postman on the left. We will concentrate on Collections and Environments in this post since we are mere users of APIs, and the other functions have more use for API developers. Collections are where we organize our API requests by sorting them into collections and Environments help to work with several environments by creating variables to use inside of requests, making them applicable to different server instances or tenants.
We won’t go into API and Mock Servers since they are mostly used for API development. They allow you to generate the API functional specifications before starting to implement them in code. Monitor allows you to create tests and check the health and performance of your API and whilst you always could batch run collections with input files. Flow allows you to build chained flows of requests with a graphic builder.

Figure 5: Postman introduction

Step 3: First Collection

While in your workspace, create your First Request collection by using the + sign next to Collections. In the collection, you can configure defaults for Authorization, tests, and variables that can be used by all requests saved in this collection. Especially for variables, we will use Environments later on.

Figure 6: First collection

Step 4: Building Requests

Now to the interesting part: building our API request! First, we need to pick the HTTP verb used in our request. You can see Postman supports most of what is available by spec, but the most common REST APIs for us to work with are GET, POST, PUT, PATCH, and DELETE. GET is used to request and receive data from a service. POST, PUT, and PATCH usually involve sending a request body to the service, as well. For now, we choose GET and move on.

Figure 7: First request

In the field next to GET, we enter our API URL. In this case, we use the Workspace ONE UEM API query for all devices managed by a specific UEM server. Pick a server that you have access to.

Figure 8: Sample device search

Depending on the server, that might be too many devices. But hey, we can use parameters with the query and only search recent devices and only Windows 10. In the Params tab of the request builder, you can define query parameters that will be added to the request URL in the right syntax automatically. So add the platform and seensince parameters and define the values we query for.

Figure 9: Request parameters

UEM won’t just let us do a query without authorization, so we need to provide credentials to send our request. In the Authorization tab, Postman allows us to specify the authorization credentials out of a list of supported methods. The most interesting for us are Basic Auth, Bearer Token, and Oauth2.

Figure 10: Request authorization

For now, we use Basic Auth using an API admin and password created at our UEM OG.

Figure 11: Request authorization

Next, we need to stop at the Header tab to add the aw-tenant-code header required to let the server know which OG to aim the request add, based on the API key we add as its value. We also add the Accept header to let the service know in which format we expect the response. (In UEM, we also use this header to let the service know which version of a specific API should send the response. For some API calls, we have 3 versions by now and they send different responses back.)

Figure 12: Request headers

Let’s just go through the other configuration tabs, even though we don’t use them for GET requests. As I mentioned with a GET request, we only request a response, but won’t send data to the service outside the limited info we can put into the params or header. If you would send a POST or PUT, you would put the data you send into the Request body. With REST APIs, this will most commonly be in JSON format. But you also have the option to simulate form-data, binary format, or GraphQL.

Figure 13: Request body

In the Tests tab, you can provide Postman scripts to automate the processing of the response. Later, I will show an example that includes parsing the JSON response of a call against an Oauth endpoint to pick up the access token, and save it into your environment variables to use them for other requests.

Figure 14: Request tests

Enough theory! Let’s check if our request works and what the response is. After clicking Send, the response is shown in the lower part of the screen. It includes the response body formatted for the expected response type of JSON, and right information like the HTTP status. The HTTP status should be 2xx for any successful request and 4xx/5xx in case something went wrong. We can also see the size of the response and how long it took the service to respond. We can search, copy, and save the response to a file we could later use as input for another collection or request.

Figure 15: Request return body

Step 5: Set Up Environments

So, this is all good for setting up a request here and there. What if you work with several environments like Dev, QA, and Production, or you are active in our beta environments? Do you need to create separate requests for every server you target? Here is where Environments come to the rescue, allowing you to create sets of variables for each environment you target and customize the requests to use the variables. Below, you can see a common set of variables used with Workspace ONE UEM and Access.

Figure 16: Environments

In our example, we change part of the request URL to the variable baseurlUEM, which is the only part that changes between the different environments, and we see how we can use the UEMAdmin and UEMPassword variables for Authorization.

Figure 17: Environment variable usage

On the top right, you can switch between the different configured environments.

Tip: Create a template environment with all required variables, and fork all other environments out of that one.

Figure 18: Environment switch

Post Example Auth into Access like a Pro

To showcase the use of a request body and automate parsing the response, let us set up authentication for Workspace ONE Access API requests. For this, we can use a service client with the client ID and client secret generated on the Access site to receive an access token that can be used as Bearer Token to authenticate our API request.

First, we need to set up that service client in Access. In the current GUI, it is in the admin portal under Catalog > Settings > Remote App Access. It has a list of all existing User or Service client tokens.

Figure 19: OAuth Client

Create a new type Service Client Token to automatically give it the admin scope, specify a Client ID, and generate a Client Secret. Both can be added to the Postman environment as variables for testing. Just remember that Postman saves them in the clear.

Figure 20: Create client

We then create a POST request to {{baseUrlAccess}}/SAAS/auth/oauthtoken, which is the endpoint to request Oauth or ID tokens with Access.

Figure 21: Create POST request

We need to authenticate against the endpoint, and we use the generated client ID and Secret here as basic auth.

Figure 22: Authenticate against the endpoint

We add a Content-Type header to let Access know what type of data we will send in the body, and set it to application/x-www-form-urlencoded, a specific way to encode key value pairs in the body.

Figure 23: Add a header

Postman fully supports this; it switches the body type, and even provides a table to add the key/value pairs. We only add a key: grant_type and value: client_credentials, thereby letting Access know we invoke the client credentials Oauth flow.

Figure 24: Key and value

Now in Tests, we add the following script to parse the JSON in the response body, and write the environment variable  BearerToken with the JSON value access_token received.

var data =  JSON.parse(responseBody);

pm.environment.set(“RefreshToken”, (data.refresh_token));

pm.environment.set(“BearerToken”, (data.access_token));

Figure 25: Add script

After sending the POST, we can see in the response body the access_token received, as well as the updated environment variable.

Figure 26: View

To test the new BearerToken, let’s add a new GET request to receive all the users on the Access tenant. The {{baseUrlAccess}}SAAS/jersey/manager/api/scim/Users does that. Now we change the Authorization to Bearer Token, and add our environment variable {{BearerToken}} to the Token field.

Figure 27: Verify

With that, we have everything set up to start testing out APIs with Postman.

Resources

Interested in learning more? Check out these great resources!

• Access REST API documentation
• UEM REST API documentation
• Postman documentation

Conclusion

This concludes Introduction to Using Postman – Part 1 of our 28-day Dev series. Watch for the Part 2 blog, where we check out some more real-world examples of what you can achieve with Postman.  

If you found this resource useful, be sure to subscribe to the Digital Workspace Tech Zone Blog RSS and 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:

• Day 1: Let's Git Commit(ted) to Dev Resources
• Day 2: Getting Started with the Workspace ONE UEM REST APIs
• Day 3: Getting Started with the Workspace ONE Access APIs
• Day 4: Getting Started with the VMware Workspace ONE Intelligence APIs
• Day 5: Getting Started with the VMware Horizon REST APIs and VMware PowerCLI
• Day 6: Getting Started with Automating the Unified Access Gateway Deployment
• Day 7: Podcast: Day 0 Onboarding Automation with Scot Curry
• Day 8: Video: Anatomy of the Workspace ONE UEM API
• Day 9: Introduction to using Postman - Part 1
• Day 10: Introduction to using Postman - Part 2
• Day 11: Pro Tips and Tricks - How to be an API Boss
• Day 12: What is OAuth - Learning the Basics
• Day 13: Getting Started with Intelligent Hub Notifications
• Day 14: Git Basics: Getting Git Going
• Day 15: Podcast: Git Commit(ted) to Resources: Customer Spotlight with The Home Depot
• Day 16: Git VMware {code} Samples and Flings
• Day 17: Using paginated requests with Workspace ONE UEM REST APIs
• Day 18: Event Notifications
• Day 19: Overview of Script Samples using PowerCLI for Horizon
• Day 20: Uploading Windows apps using REST APIs 
• Day 21: Uploading macOS apps using REST APIs and Admin Assistant 
• Day 22: API-based user lifecycle and SCIM 
• Day 23: Video: Community Expert Roundtable on Leveraging APIs and Scripting
• Day 24: Video: Exploring the Workspace ONE GitHub Samples Repository 
• Day 25: Featured Fling: Forklift for Workspace ONE UEM
• Day 26: Featured VMware {code} Samples for Horizon
• Day 27: Featured Flings for VMware Horizon
• Day 28: Continuing to Focus on </Dev> Resources Page