About

Overview

Parallels RAS comes with various APIs to help you develop custom applications that integrate with it. The RAS REST API is one of them. This guide describes how to use the REST API and documents the available REST resources, complete with request syntax and examples.

Getting Started

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>:20443/api/<URI>

where:

<API-host> is the IP address or FQDN of the server on which the RAS REST API endpoint is installed.
<URI> is a path to a REST resource that you would like to work with. The available resources and their paths and possible parameters are described in the OPERATIONS section. Request body schemas are documented in the SCHEMA DEFINITIONS section.

Logging in and Sending Requests

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

Login to Parallels RAS and obtain an authentication token.
Retrieve the information about all available RD Session Hosts.
Retrieve the information about a specific RD Session Host.
Modify RD Session Host properties.

Log in to Parallels RAS and obtain an authorization token

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

POST https://<API-host>:20443/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 authentication token, which you will use in all subsequent requests:

{
 "authToken": "[AUTHENTICATION_TOKEN]"
}

Throughout this document, AUTHENTICATION_TOKEN refers to the authentication token, which can be obtained from /api/session/logon.

Retrieve information about RD Session Hosts

Now that we have the authentication 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>:20443/api/RDS

Request headers

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

Content-Type: application/json; api-version=1.0
auth_token: [AUTHENTICATION_TOKEN]

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 in the end:

GET https://<API-host>:20443/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>:20443/api/RDS/2/

Note "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: [AUTHENTICATION_TOKEN]

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>:20443/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
}

Examples

Below you can find some samples containing sequences of different types of HTTP requests:

Basic Sample How to start a session, get all sites, get a particular site, get all gateways, add a new Secure Gateway, get a particular Secure Gateway, create an RDS server, get the RDS server status, get the RDS server sessions.

RDS Sample How to get all RDS servers, add a new RDS Server, get the its status, get its sessions, add the Server to a RDS Group, update the RDS Group.

Publishing Sample How to manage published resources and use filtering options.

Connection Broker and Secure Gateway Sample How to manage Publishing Agents and Gateways.

Licensing Sample How to manage license.

NextAPI reference