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

API1

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:

API2

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.

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.

api-documentation

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!