Using the VMware Horizon Server REST API

Introduction

VMware Horizon® has had VMware PowerCLI and Horizon View API for many years, which is great for handling automation and reporting, but the Horizon View API relies on Microsoft PowerShell and the VMware PowerCLI tool. Many enterprises now want to use other languages or create compiled applications, and that can be difficult with PowerCLI. To meet these needs, in Horizon 7.10, a RESTful API was introduced.

Purpose of This Guide

With this release of the VMware Horizon Server REST API, many new API endpoints have been added so that you can now use the REST API to do day-two operations and automations. This guide introduces you to the REST API and provides examples of how to use the endpoints in combination to achieve your goals.

Intended Audience

This information is intended for anyone who wants to use the Horizon Server REST API for automation or reporting purposes in their VMware Horizon environment. The information is written for experienced administrators who are familiar with virtual machine technology and data center operations. Readers should also have some familiarity with:

• Concepts related to RESTful APIs. If you are not familiar with REST concepts, see the Wikipedia entry for Restful state transfer (REST).
• JavaScript Object Notation (JSON) format. If you are not familiar with this industry-standard file format, see the Wikipedia entry for JSON.
• Swagger open-source tools, which you might use for accessing the Horizon Server REST API documentation. For more information, see the Getting Started with Swagger.
• Postman tool for testing calls to the API. For more information, see the Postman Learning Center.
• An individual API call is called an endpoint in this document.

Benefits of RESTful APIs

The major benefit that the restful state transfer (REST) architectural style really gives scripters and developers is consistency.

• Consistency across products – You can interact with a REST API from one product in the same way as from another.
• Consistency in data format –The data returned is consistent. It is typically returned as JSON or XML, which is easy to deserialize. The Horizon Server REST API returns data in the JavaScript Object Notation (JSON) format.

By returning the data in JSON format, we can consistently and easily return data from the API. An API is not very useful if it is difficult to get data out of. By using the standard of a REST API, Horizon makes it easy to get data out and manage automation. When data is posted to the API, the data should also always be valid JSON. 

 

I recommend using a site like JSON Lint to format and make the JSON string easier to read and to also verify validity when posting JSON strings back to the API.

Resources for Learning About the Horizon Server REST API

There are several places you can go to learn about the REST API in Horizon. 

• code.vmware.com – Horizon Server API Reference
• Local Swagger on installations of Horizon 2006 and later – 
  https://<fqdn-of-connectionserver>/rest/swagger-ui.html
• code.vmware.com - Postman Collection – Horizon REST API – Postman collections for each version of the Horizon Server REST API
  These are used to quickly return data and learn about the API. We will use Postman and this collection as examples throughout this document.
• Horizon REST API Pagination and Filter Guide

Horizon Server REST API Endpoints

The following table provides an overview of the APIs available with the Horizon Server REST API.

Note: As mentioned earlier, the Horizon Server REST API can be reviewed on code.vmware.com or locally with Swagger at https://<fqdn-of-connectionserver>/rest/swagger-ui.html.

Table 1: Breakdown of the Horizon Server REST API 

API Endpoint	Description
Auth	APIs for authentication and authorization. Used to log in to or out of the Horizon Server REST API.
Config	APIs for managing configuration items such as environment properties, the Horizon Image Manage Service, Horizon Connection Server general settings and security settings, and listing VMware vCenter Server® instances associated with the environment.
Entitlements	APIs for managing user entitlements for application and desktop pools.
External	APIs for retrieving information external to the Horizon environment. These include information from Active Directory and vCenter Server.
Inventory	APIs for creating, updating, and deleting application and desktop pools; getting information on pools; adding machines to manual pools; getting information on RDSH server farms; and managing machines and sessions.
Monitor	APIs for monitoring. These are all GET endpoints for Horizon and related services.

We will cover an example in each section of the API in the sections that follow.

 

Logging In to the Horizon Server REST API

The Horizon Server REST API uses a JSON Web Token (JWT) for securing access to the API endpoints. This JWT is initially obtained by authenticating to the /login endpoint. The access token, along with a refresh token used to acquire a new access token, is returned as a JSON string. The access token is added to each API call as an Authentication header. (This will be covered later in this document.) In order to access the REST API, the user must be an administrator at /Root.

Important: The provided Postman collection uses variables to authenticate to the Horizon server, and it automatically appends the Authentication header for every API call while the session is active. For directions on configuring the Postman collection, see Postman Collection - Horizon REST API.

Authentication Example

To use this example, replace items in bold text with the appropriate values for your environment:

Verb: POST
URL: https://fqdn-of-connectionserver/rest/login
Body: {"username":"myusername","password":"mypassword","domain":"mydomain"}

Figure 1: Logging In to the API

Figure 2: Example of Data Returned from Logging In to Horizon Server REST API with Postman

We can see that the access token and refresh token are returned when we successfully authenticate to the API. The access token is used to authenticate each API call, and it is added to an Authentication header as follows: Bearer {access_token}

The refresh token, which has a longer validity timespan, can be used to get a new access token when the current access token expires.

Lifetime of tokens:

• Access token: Default is 30 minutes.
• Refresh token: Default is 8 hours.

The defaults for lifetime of tokens can be adjusted in the Connection Server ADAM database, with the pae‑RestAuthConfig attribute under CN=Common,OU=Global,OU=Properties,DC=vdi,DC=vmware,DC=int, as shown in the following figure.

Figure 3: REST API Configuration in ADAM

Config APIs

These API endpoints are used to retrieve and set configuration items such as:

• Horizon pod environment properties
• Instant-clone domain account
• Horizon Image Management Service
• Universal broker plugin
• vCenter Servers used with Horizon

In the following example, we will return the global pod settings, including settings shown on the General Settings tab, the Client Restriction Settings tab, and the Security Settings tab, as well as feature flag settings, which are not available in the Global Settings window.

 

Example: Retrieving a List of Global Settings

To use this example, replace items in bold text with the appropriate values for your environment:

Verb: GET
URL: https://fqdn-of-connectionserver/rest/config/v1/settings
Authentication Header: Bearer eyJ…u5A

Figure 4: Data Returned from REST API – Global Settings

Figure 5: Global Settings in the Admin UI

Entitlement APIs

These API endpoints are used to list, create, or delete application pool and desktop pool entitlements. In order to create an entitlement, we need to use some other APIs. We need to:

1. Get the ID of the application or desktop pool.
2. Get the ID of the user or group we want to entitle.
3. Add an entitlement to the pool, using the ID of the pool and the ID of the user or group. We will cover an example in Postman of adding a group entitlement to an existing desktop pool.

Example: Using an Inventory API to Return the ID of a Desktop Pool

For this example, we want to return the ID of the desktop pool named IC_DesktopPool.

To use this example, replace items in bold text with the appropriate values for your environment:

Verb: GET
URL: https://fqdn-of-connectionserver/rest/inventory/v2/desktop-pools
Authentication Header: Bearer eyJ…u5A

Figure 6: Output of API Returning Desktop Pools

We can see the desktop pool called IC_DesktopPool and the ID of the pool. That ID is used to manage the pool. We will copy this value and save it for now.

Example: Using an External API to Return the ID of a User Group

We want to entitle a group called Windows-10-VDI.

1. First, we need to define a filter that will return the group that we want, as described in Creating a Filter.
2. Once we have a URL-encoded filter string, we can use that to retrieve the ID of the group, as described in Using the URL-Encoded Filter String to Retrieve the Group ID.

Creating a Filter

Several of the API endpoints support pagination and filtering. See the VMware Horizon Server API reference for more details.

Note: Download the Horizon REST API Pagination and Filter Guide for more details on using filters.

According to the guide, we need the following filter to return our group ID:

{
"type":"Equals",
"name":"name",
"value":"windows-10-vdi"
}

Now, we cannot just pass in this JSON as it is. Because we are making a GET call, we need to append this filter as a parameter to the URL. We also need to URL-encode the string to make sure it can be read properly by the API.

Before URL-encoding the string, it is recommended to minify the JSON string by removing unnecessary spaces. Any way of URL encoding with UTF-8 encoding can be used. We will use a website in this case. We pass in the query filter JSON and select the control to encode it. The page will give us the URL-encoded string. We will pass this into the API call as a parameter.

Figure 7: URL-Encoding the Filter

Now that we have the URL-encoded value of the filter, we can provide it to our API and return the ID of the group that we want to entitle.

Using the URL-Encoded Filter String to Retrieve the Group ID

To use this example, replace items in bold text with the appropriate values for your environment:

Verb: GET
URL: https://fqdn-of-connectionserver/rest/external/v1/ad-user-or-groups
Authentication Header: Bearer eyJ…u5A
Parameter: filter={URL Encoded Filter String}

Figure 8: Get the ID of the Active Directory Group

Example: Using an Entitlements API to Entitle a User Group to a Pool

Finally, we can run the API to entitle the user group to the desktop pool. This API requires that we provide the ID of the AD user or group we want to entitle and the ID of the desktop pool we wish to entitle them to. This data is passed in via JSON. To make sure that the JSON string is formatted correctly, use a site such as JSON Lint.

To use this example, replace items in bold text with the appropriate values for your environment:

Verb: POST
URL: https://fqdn-of-connectionserver/rest/entitlements/v1/desktop-pools
Authentication Header: Bearer eyJ…u5A
Body:

[{
"ad_user_or_group_ids":["id-of-user-or-group"],
"id":"id-of-desktop-pool"
}]

 

Figure 9: API Call to Entitle a Desktop Pool

The API is a bulk-operation API, and the response will contain a list of status details (one for each of the operations in the request). We can see we got back a 200 status, which means our operation was processed without any errors.

If we look in the Horizon Console, we can see that the group entitlement for windows-10-vdi was added to the desktop pool IC_DesktopPool.

Figure 10: Entitlement Shown in Horizon Console

External APIs

These APIs are used to query real-time information from systems external to Horizon. We already used one of the External APIs to return information on an Active Directory group, in Example: Using an External API to Return the ID of a User Group. In addition, we can return the following information:

• AD domains and users/groups
• vCenter objects, including VM templates, base VMs, VM snapshots, customization specs, datastores, NICs, VMware vSphere® hosts/clusters, folders/tags, and resource pools

Inventory APIs

These APIs are used to manage the Horizon environment. We already used one of the Inventory APIs to return information on desktop pools, in Example: Using an Inventory API to Return the ID of a Desktop Pool.

With these APIs you can do the following:

• List application icons
• Manage application pools: list pools, create pools, update pools, and delete pools
• Manage desktop pools: list pools, add machines to and remove machines from manual pools, retrieve a list of installed applications per desktop pool (used for the VM-Hosted Application feature)
• Manage RDSH server farms: list farms and list applications installed on servers in the farm
• Manage Horizon desktops: list machines, delete machines, assign users to and unassign users from machines, manage maintenance mode, rebuild, recover, reset, and restart machines
• Manage Horizon sessions: list sessions, disconnect users from the machine, log users off the machine, reset, restart, and send a message to the session

Monitor APIs

This is a set of APIs that return the status of various Horizon-related services. These are all GET endpoints, which return data used for monitoring the services. They include monitoring of:

• Active Directory
• Connection Servers
• Events database
• RDSH servers and server farms
• Gateways
• SAML authentications and True SSO connections
• vCenter Servers

In the following example, we return monitoring information for Horizon Connection Servers. This can be used to see the status of various components, such as security and Blast gateways, and to see details such as connection count.

Example: Monitoring a Connection Server

To use this example, replace items in bold text with the appropriate values for your environment:

Verb: GET
URL: https://fqdn-of-connectionserver/rest/monitor/v2/connection-servers
Authentication Header: Bearer eyJ…u5A

Figure 11: Connection Server Monitoring API

Summary

We hope this guide has helped you understand the basics of Horizon Server REST API usage. Be sure to also review the latest documentation on code.vmware.com for the latest features and updates to the Horizon Server REST API.

Changelog

The following updates were made to this guide.

Date	Description of Changes
2022-02-24	This guide has been reviewed and the content is up to date
2020‑08‑11	Initial version of the document for Horizon 8 (2006)

Author and Reviewers

Author

Chris Halstead is an End-User Computing Staff Architect, EUC Technical Marketing, VMware.

Reviewers

• Dileep Thiagarajan, Senior Product Manager, VMware
• Prashant Surad, Senior Member of the Technical Staff (MTS), VMware
• Rahul Agarwal, Senior Member of the Technical Staff (MTS), VMware

To comment on this paper, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.