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 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.

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
    }
]

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 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 https://kb.parallels.com/en/124701.

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.

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