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