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:
Response
After sending the logon request, you will receive a reply containing the authentication token, which you will use in all subsequent requests:
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.0auth_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):
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.0auth_token: [AUTHENTICATION_TOKEN]
Request body
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:
Examples
Below you can find some samples containing sequences of different types of HTTP requests:
Was this helpful?