Introducing the Altaro VM Backup API

A while back during one of our webinars on scripting and automation, we announced that our flagship product, Altaro VM Backup, now contains a usable RESTful API. We promised that we would be providing more information to the public about this new functionality and now we’re delivering!

Introductions

As the strain of more work and smaller budgets begin to weigh heavily on IT departments everywhere, many IT administrators are turning to automation and scripting to do things more quickly and efficiently than ever before. When we set out to create this API, we wanted to make our product as flexible and powerful as possible. The Altaro VM Backup API provides users of our application extreme, granular control over the application and it’s functions. You can perform a number of different functions using our API, such as adding a VM to a backup schedule, assigning backup locations, pulling schedule information and much, MUCH more.

Our API can be used for some more advanced automation as well, for example, upon the deployment of a new virtual machine, you have a line in your script that calls the Altaro VM Backup API and automatically adds the new VM to your standard backup routines. Another example would be pulling various backup status information out of our application and incorporating it into a dashboard system for easy access to backup status information along with your other needed metrics. The sky really is the limit, and we’re excited to see what creative uses customers come up with, once they have their hands on this API.

Getting Started

So the first question on everyone’s mind will be, “How do I get started?” Let’s walk through that now. You can download Altaro VM Backup from here.

By default, the service that runs the API on the Altaro VM Backup server is in a disabled state. It first needs to be enabled.

On the machine running your Altaro VM Backup software, change the startup type for the “Altaro VM Backup API Service” service to automatic, and then start the service.

From there, all API calls start with the base URL: http://localhost:35113/api. From there the URL changes a bit based on the API call needed, and various actions can be taken. This is all well and good for those people that are familiar with RESTful APIs, but what if you’re more on the operations side and don’t deal with all the DevOps stuff all the time. How do you get to leverage these APIs? One word, PowerShell.

We’ve shipped a large number of pre-written PowerShell scripts that are designed to call these various APIs and carry out their functions by using the Invoke-RestMethod cmdlet. The good news for the operations people is that you don’t need to know much PowerShell to use our pre-configured scripts. By default they are located at: C:\Program Files\Altaro\Altaro Backup\Cmdlets\ on the machine that is running the Altaro VM Backup Software. Using these scripts  and getting useful information out of the API really consists of three steps.

1. Establish a new Session with the Altaro VM Backup API
2. Call Needed APIs
3. Close Session

We require a new session token be established with the API to act as an authentication mechanism. Most of the scripts mentioned above require that the session token obtained by opening an API session, be used as a command line parameter to make sure the user is properly authenticated.  Failing to add said session token will cause the API call to be unsuccessful.

This session token can be generated easily by running either the StartSessionPasswordHidden.ps1 script or the StartSessionPasswordShown.ps1 script in the directory mentioned earlier. They need to be run with certain parameters. Username, Password, and Hostname/Domain, as shown in the example below

.\StartSessionPasswordHidden.ps1 <username> <domain or hostname>

NOTE: The StartSessionPasswordHidden.ps1 script prompts the user for the password instead of including it inline as an argument as the StartSessionPasswordShown.ps1 script will. This is because the first script is to be used interactively, while the second one is for scripting and automation scenarios.

You can see that the script produces some output in JSON format, with the “Data” field, being the important section. This is the new session token that has just been opened for the API. All subsequent commands will need to reference this session token in order to work properly.

From here, you can use any of the pre-configured scripts by running the desired script and passing the session token value as an argument. For example, if I want to return a list of all backup schedules, I could do so manually by running the following:

.\GetSchedules.ps1 <session token>

This will return a list of all defined schedules in the Altaro VM Backup instance and return them in JSON format to the CLI as shown below:

Once you’ve returned the needed information and you’re done with the API, the session can be closed by issuing either:

.\Endsession.ps1 <session token>

to end just the target session, or you can simply run the EndAllSessions.ps1 script to end all active API sessions.

Congratulations, you’ve just utilized our API for the first time!

Limitations

As this is an early version of our API, there are some limitations which may be lessened or removed in future releases. We wanted to get a working API out to our customers to start getting some feedback. At any rate, there are a few limitations to be aware of:

1. The API only works locally on the machine that contains the Altaro VM Backup software. You can still call scripts remotely, however, the machine accessing the API has to be the machine that is also hosting the Altaro VM Backup API Service.
2. An API Session and a GUI Session cannot be open at the same time. If the management GUI is open and connected, an API call will fail at this point in time and vice-versa.
3. PowerShell Version 3 or higher is REQUIRED.
4. Anything NOT at the VM level like adding and deleting backup locations, schedules, and notification servers are not currently supported by the API.

Next Steps

The collection of PowerShell cmdlets mentioned above can serve as a good starting point for learning how to utilize the API. They are great in situations where you just want to execute a couple of commands to return some basic information. However, what if you want to do this in a more automated fashion? What if you wanted to pull this information for a scheduled report? That is a possible use case. The problem is, you may not be sitting at the keyboard to issue the needed commands. In this case you can utilize the Invoke-RestMethod cmdlet in a PowerShell script of your own crafting to make the API do exactly what you want it to do.

For example. I’ve crafted the below script, which basically acts as all three of the above scripts we just used, in one script. It will essentially retrieve a session token, pull a list of schedules, output them to the console, and then close the session. Take a look through the script. I’ve commented it heavily so people can use it within their own organizations as needed.

NOTE: I also took liberal use of the sleep command throughout the script. This was mainly to provide more organic status updates to the user while the script was running. Otherwise some of the output would be confusing if not broken up properly. Also you may have to expand the code window to see all of the relevant code, depending on your viewing resolution.

# DISCLAIMER: There are no warranties or support provided for this script. Use at you're own discretion. Andy Syrewicze and/or Altaro Software are not liable for any
# damage or problems that misuse of this script may cause.

# Script is Written by Andy Syrewicze - Tech. Evangelist with Altaro Software and is free to use as needed within your organization.



# We first verify that the execution policy is set to unrestricted and then verify the needed version of PowerShell is present

Set-ExecutionPolicy -ExecutionPolicy Unrestricted

if([int]$PSVersionTable.PSVersion.ToString().Substring(0,1) -le 2)
{
    Write-Warning "PowerShell version " $PSVersionTable.PSVersion "is not supported. Only PowerShell versions 3 and onwards are supported" -Verbose
    Break
}

############################## ------ This Section Contains all user definable variables ------ ##############################

# The Below is used at various locations throughout the script
# NOTE: a local server hostname can be used here as well for stand-alone system situations, where a domain is NOT present
# NOTE: The values below go *WITHIN* the double quotes Example: $AltaroUser = "BilboBaggins"

$LocalADDomainFQDN = "Domain or Hostname Here"

# Altaro VM Backup Instance Credentials are defined below

$AltaroUser = "Altaro User Accountname Here"
$AltaroPassword = "Altaro Password Here"

######################## ------ The below contains variables that are NOT changable at this time ------ ######################

# The below variables define the location of the Altaro VM Backup API Service. 
# NOTE: currently the API can only be called locally on the machine containing the service.
# NOTE: DO NOT EDIT THESE AT THIS TIME!

$AltaroServiceAddress = "http://localhost:35113/api"
$AltaroServerPort = "35107"
$AltaroServerAddress = "LOCALHOST"

##############################################################################################################################




################################### ------ Script Execution from this Point Forward ------ ###################################

# The Below first gathers the needed information then Calls the Altaro VM Backup REST API and Opens a Secure Session. The  
# Session Token is then saved as variable $AltaroSessionToken and the Session Token UID can be called for subsequent  
# operations by referencing $AltaroSessionTokenUID

$NewSessionAPIInput = @{
                ServerAddress = $AltaroServerAddress; 
                ServerPort = $AltaroServerPort; 
                Username = $AltaroUser; 
                Password = $AltaroPassword; 
                Domain = $LocalADDomainFQDN
         }

$AltaroNewSessionUri = $AltaroServiceAddress + "/sessions/start"
$NewSessionAPIResult = Invoke-RestMethod -Uri $AltaroNewSessionUri -Method Post -ContentType "application/json" -Body (ConvertTo-Json $NewSessionAPIInput)
$NewSessionTokenJson = $NewSessionAPIResult | ConvertTo-Json
$AltaroSessionToken = $NewSessionTokenJson | ConvertFrom-Json
$AltaroSessionTokenUID = $AltaroSessionToken.Data

# The Below Statement checks to make sure that the $AltaroSessionTokenUID variable has been successfully written and if not, it will stop the script's execution. 

If ($AltaroSessionTokenUID -eq $null)
{
    Write-Warning "Failed to get Session Token from the Altaro VM Backup API. Please check your variables and verify that the Altaro VM Backup API Service is in a running state, and try again." -Verbose
    Break
}
Else
{
    Write-Verbose "Connection to the Altaro VM Backup API has been established and session token is being obtained" -Verbose
    Sleep 3
}

Write-Verbose "Altaro VM Backup Session Token UID is:[$AltaroSessionTokenUID]" -Verbose
Sleep 3


# Uncomment the below lines to pull schedule information from the target Altaro VM Backup Instance and display it in the
# console window

Write-Verbose "Fetching Altaro VM Backup Schedule Information. Please Stand By." -Verbose
Sleep 3

$AltaroSchedulesUri = $AltaroServiceAddress + "/schedules/" + $AltaroSessionTokenUID
$AltaroSchedulesResult = Invoke-RestMethod -Uri $AltaroSchedulesUri -Method Get -ContentType "application/json"
$AltaroScheduleList = $AltaroSchedulesResult | ConvertTo-Json
Write-Output $AltaroScheduleList
sleep 3

# The below code closes the session to the Altaro VM Backup API once completed.
# NOTE: You want to run the below block of code last

Write-Verbose "All operations complete. Closing Session" -Verbose
Sleep 3

$AltaroEndSessionUri = $AltaroServiceAddress + "/sessions/end/" + $AltaroSessionTokenUID
$AltaroEndSessionResult = Invoke-RestMethod -Uri $AltaroEndSessionUri -Method Post -ContentType "application/json"
$AltaroEndSessionJson = $AltaroEndSessionResult | ConvertTo-Json
$AltaroEndSessionStatus = $AltaroEndSessionJson | ConvertFrom-Json
$AltaroEndSessionStatusData = $AltaroEndSessionStatus.Success

# The Below Statement checks to make sure that session has been sucessfully closed, and if not, notifies the user on next steps. 

If ($AltaroEndSessionStatusData -eq "true")
{
    Write-Verbose "Active Session to Altaro VM Backup API has been successfully closed" -Verbose
}
Else
{
    Write-Warning "Failed to close the Altaro VM Backup API connection. Please manually run the EndAllSession.ps1 script located in C:\Program Files\Altaro\Altaro Backup\Cmdlets\ on the server running the Altaro VM Backup Software." -Verbose
}
Sleep 3
Write-Verbose "End of Script" -Verbose

##############################################################################################################################.

The script looks complicated, but once you start reviewing some of our pre-buillt scripts and begin fashioning your own, you’ll find that the process is fairly straight forward.

If you’re interested in more detailed API documentation you can find it on our support site below. You can also download a 30-day trial, or the Free version of Altaro VM Backup here.

Wrap Up

Other than that, we hope you’ve enjoyed this first look into our Altaro VM Backup REST API, and we’re excited to get your feedback and hear about your potential use cases as you begin to use it within your environment. Feel free to let us know about your experience in the comments section below!

Enjoy!