Parallels RAS comes with APIs to help you develop custom applications that integrate with it. This includes RAS PowerShell API and RAS REST API.

In addition, the RAS Web Client API and Parallels Client URL scheme allow you to integrate with Parallels Client for Windows/macOS/Linux/iOS/Android and the Web Client.

This section gives you an introduction to the RAS REST API. Read it to learn about system requirements, installation, configuration, and basic usage.

RAS PowerShell API is intended for RAS administrators who would like to automate their RAS administration. The API includes commands to perform most of the RAS management tasks.

Parallels RAS requirements

The Parallels RAS PowerShell API version must match the version of the RAS Connection Broker with which it communicates. Since the two components can be installed separately, you need to make sure that their versions match.

Microsoft Windows component requirements

The following components must be installed on the computer where you'll be executing Parallels RAS PowerShell cmdlets:

• Windows PowerShell 3.0 or higher

• Microsoft .NET Framework 4.5.2 or higher

Installation

To install Parallels RAS PowerShell, run the standard Parallels RAS installer, choose Custom installation, and then select to install the Parallels RAS PowerShell component. Follow the onscreen instructions to install the component.

RAS PowerShell API versions

The RAS PowerShell API has undergone changes in Parallels RAS 18 as follows:

• The RAS PowerShell module name has changed from PSAdmin to RASAdmin.

• Most of the commands now have the "RAS" prefix, such as RASGW or RASApply.

• API versions: Version 2.0 (latest) and version 1.0 are supported for backward compatibility.

Note that the API version 1.0 is still available in the current RAS PowerShell module. If you have existing scripts that use the older module and command names, you can use them with minimal changes. To do that, you need to load the API version 1.0 when you import the RAS PowerShell module. See below for more information about API versions.

Version 2.0

This version is the one loaded by default by the system or if the -RequiredVersion parameter is not specified when importing the module. See RAS PowerShell API concepts for examples.

Version 1.0

This version keeps backward compatible with the old PSAdmin module to allow administrators to use existing scripts with minor modification. This version includes:

• Cmdlet aliases

• Aliased parameters

• Returns old and new properties

RAS PowerShell API concepts

To quickly get started with RAS PowerShell, do the following:

1. Open the Windows PowerShell console.

2. Import the Parallels RAS PowerShell module using one of the following commands:

   • Import-Module RASAdmin — Loads the current API (version 2.0).

   • Import-Module RASAdmin -RequiredVersion 1.0 — Loads the API version 1.0.

3. Create a Parallels RAS session by executing the New-RASSession cmdlet (see example below). Substitute the server name (in quotes) with the name or IP address of your Parallels RAS Licensing Server. Type your RAS administrator username and password when prompted:

   New-RASSession -Server "server.company.dom"

4. Execute the following cmdlet to see the list of cmdlets included in the Parallels RAS PowerShell module:

   Get-Command -Module RASAdmin

5. Execute other cmdlets. For example, try executing the Get-RASW cmdlet to retrieve information about RAS Secure Gateway(s). The example below returns information about all RAS Secure Gateways available in the RAS Licensing Server Site:

   Get-RASGW

6. To see help for a cmdlet, execute Get-Help passing a cmdlet name:

   Get-Help Get-RASGW

7. To apply changes you've made to the Farm configuration, use the Invoke-RASApply cmdlet (this performs the same action as the Apply button in the RAS Console):

   Invoke-RASApply

8. To activate a Parallels RAS license, use the Invoke-RASLicenseActivate cmdlet:

   Invoke-RASLicenseActivate

   When executing the cmdlet above, you'll be prompted to enter your Parallels account email address and password. You can include an optional -Key parameter and specify a Parallels RAS license key. If omitted (as in the example above), Parallels RAS is activated as a trial.

Parallels RAS PowerShell Guide

To view and download the new Parallels RAS PowerShell Guide version 2.0, visit Parallels website at https://www.parallels.com/products/ras/resources.

This section contains an example of RAS REST API usage that can help you quickly get started. The example demonstrates how to:

1. Login to Parallels RAS and obtain a session token.

2. Retrieve the information about all available RD Session Hosts.

3. Retrieve the information about a specific RD Session Host.

4. Modify RD Session Host properties.

Log in to Parallels RAS and obtain a session token

Before you can access any of the resources, you need to log in to Parallels RAS using administrator credentials and obtain a session token. This is accomplished by sending the following request:

POST https://<API-host>/api/session/logon

Request headers: The logon request must contain just the Content-Type request header. Subsequent requests must additionally contain the auth_token header, as you'll see in the examples that follow this one.

Content-Type: application/json; api-version=1.0

Request body: The request body must contain the RAS administrator user name and password.

{
 "username": "USER",
 "password": "PASSWORD"
}

Response: After sending the logon request, you will receive a reply containing the session token, which you will use in all subsequent requests:

{
 "authToke	n": "Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq"
}

Retrieve information about RD Session Hosts

Now that we have the session token, we can send requests to access various resources. In this example we'll first obtain the information about all available RD Session Hosts. In the example that follows, we'll obtain the information about a specific RD Session Host.

To retrieve the RD Session Host info, send the following request:

GET https://<API-host>/api/RDS

Request headers: This time the auth_token request header must also be included and must contain the session token that we've obtained earlier.

Content-Type: application/json; api-version=1.0

auth_token: Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq

Response: The response will look similar to the following (with multiple RD Session Hosts in the Farm each block of the result set will contain the information about an individual server).

[
    {
        "directAddress": "IP_ADDR",
        "rasTemplateId": 0,
        "inheritDefaultAgentSettings": true,
        "inheritDefaultPrinterSettings": true,
        "inheritDefaultUPDSettings": true,
        "inheritDefaultDesktopAccessSettings": true,
        "port": 3389,
        …
        "restrictDesktopAccess": false,
        "restrictedUsers": [],
        "server": "IP_ADDR",
        "enabled": true,
        "description": "",
        "siteId": 1,
        "id": 2
    }
]

Retrieve information about a specific RD Session Host

To retrieve the information about a specific server, we'll use the same request as above but will add the server ID at the end:

GET https://<API-host>/api/RDS/2/

The response will also be similar to the example above and will contain the information just for the specified server.

Modify RD Session Host properties

In this example we'll modify a property of the RD Session Host that we retrieved earlier. For simplicity let's modify the "description" field.

The request to modify properties of an RD Session Host has the following syntax:

PUT https://<API-host>/api/RDS/2/

Note the "2" at the end of the request, which specifies the ID of the RD Session Host that we want to modify.

Request headers:

• Content-Type: application/json; api-version=1.0

• auth_token: Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq

Request body:

{
    "description": "description was updated!"
}

Response: If the PUT request succeeds, you will get an empty response with code "204: No Content". To verify that the "description" field was in fact modified, let's use the same GET request that we used earlier: GET https://<API-host>/api/RDS/2/

As we can see, the result now contains the updated "description" field:

[
    {
        "directAddress": "IP_ADDR",
        "rasTemplateId": 0,
        "inheritDefaultAgentSettings": true,
        …
        "server": "IP_ADDR",
        "enabled": true,
        "description": "description was updated!",
        "siteId": 1,
        "id": 2
    }
]

Applications communicate with Parallels RAS by sending HTTP or HTTPS requests. Parallels RAS answers with a JSON file in a response to every HTTP request.

All HTTP requests that you will use to retrieve and manage Parallels RAS resources have the following base structure:

https://<API-host>/api/<URI>

The parameters in the above URL are:

• <API-host> is the IP address or FQDN of the server on which the RAS Web Administration Service is installed.

• <URI> is a path to a REST resource that you would like to work with.

To enable RAS REST API in a RAS Farm, you need to install the RAS Web Administration Service. It can be installed on the RAS Connection Broker server or any other server. If you install the service on a separate server, you will need to change its configuration (after the installation) to point to RAS Connection Broker. By default, the configuration points to "localhost".

To install RAS Web Administration Service:

1. Run the Parallels RAS installer on the RAS Connection Broker or any other server.

2. On the Select Installation Type page, select Custom.

3. On the next page, select to install the Parallels RAS Web Administration Service component.

4. Click Next and follow the onscreen instructions.

Configure RAS Web Administration Service

If the RAS Web Administration Service was installed on a separate server, you need to modify its configuration and specify the RAS Connection Broker server address. You may also want to change the port number and certificate information in the same configuration file. For details about configuring RAS Web Administration Service, please refer to KB article .

When modifying the service configuration, please note the following:

• In the configuration JSON file, the RAS Connection Broker address is specified using the "LicenseServer" parameter.

• The default HTTPS port number is set to 20443. This number is chosen not to conflict with RAS Secure Gateway ports. You can change it to 443 (if possible), so when opening the portal, you don't have to include the port in the URL.

RAS Web Client API and Parallels Client URL scheme allow you to integrate with Parallels clients.

Using the RAS Web Client API or the URL scheme, you can implement an in-house solution, such as an application hub or web portal, for authenticating users and launching remote applications, desktops, and other published resources. Such an implementation is possible by integrating a custom solution with Parallels Clients, including Parallels Clients for supported platforms (Windows, macOS, Linux, iOS, Android) and RAS Web Client.

The following is a quick summary of the API and the URL scheme:

• RAS Web Client API — provides connection, user authentication, and resource launching methods called from a web browser via Web Client.

• Parallels Client URL scheme — a custom URL scheme that allows you to perform actions in a Parallels Client installed on a user device. Actions include configuring a connection, authenticating a user, and launching published resources.

RAS Web Client API and Parallels Client URL scheme are described in detail in the Integrating with Parallels Clients guide, which is available for download on the Parallels website at the following location: .

Parallels RAS REST API comes with the Parallels RAS REST API Guide. The guide contains more examples and the complete resource and schema reference. To view and download the guide, visit https://www.parallels.com/products/ras/resources/.

To access any of the RAS REST resources, the user executing a request must have sufficient rights to access a particular resource. These are basically the same rights a RAS administrator has in the Parallels RAS Console. For example, a root administrator can access any of the RAS REST resources. On the other hand, a power administrator who doesn't have rights to modify Site settings (as an example) will not be able to access a corresponding REST resource. Similarly, a custom administrator who, for instance, only has rights to view and modify RD Session Hosts will be able to access just that particular REST resource and no other.