Using the API

The Windows Service which enables API calls is disabled by default and it must be enabled manually before the API can be used. To enable the service, the following steps should be followed:

Pre-requisites

1. Open the Windows Services window. One way of doing so is by running the command services.msc.
2. Right click on Altaro VM Backup API Service, and click on Properties.
3. Change Startup type to Automatic
4. Click OK to save the changes.
5. Once again right click on Altaro VM Backup API Service, and click on Start.

All of the API calls start with the Base URL: http://localhost:35113/api

The next part of the URL subsequently changes according to the API call in question.

The API can only be accessed on the same machine and no remote connections are allowed. This means that if the Altaro VM Backup Installation resides on the machine 192.168.1.1, the API service must also reside on 192.168.1.1. If another Altaro VM Backup Installation is running on 192.168.1.2, the aforementioned API service cannot be used to connect to such an Agent.

The Altaro API can also be accessed through the PowerShell Cmdlets. These are located in the Cmdlets folder in the Altaro VM Backup installation directory. The default cmdlet directory is:

C:\Program Files\Altaro\Altaro Backup\Cmdlets

To use the Cmdets, version 3 onwards of PowerShell is required. Every Cmdlets comes with its particular usage. An example is also provided in the usage in order to facilitate usage of such cmdlets. The usage can be printed on screen using the following command:

cmdlet_name.ps1 –help

For simplicity, the above command assumes that the current directory has been changed to the directory containing the cmdlets. If this were not the case, the cmdlet has to be called using the following command:

&("path_to_cmdlet_directory\cmdlet_name.ps1") --help

The above commands are in a generic form. The following are a concrete example to print the usage of the start session with hidden password cmdlet. The following commands assume that the default installation directory has been used to install Altaro VM Backup and that the Cmdlets were not moved to another directory.

./StartSessionPasswordHidden.ps1 –help

&("C:\Program Files\Altaro\Altaro Backup\Cmdlets\StartSessionPasswordHidden.ps1") --help

The usage describes the cmdlet and its parameters. It also shows basic examples with different combinations of how the cmdlet can be used. With this usage, it should be pretty straightforward to use the API using PowerShell. All cmdlets return a JSON object which contains the HTTP response which the API service replied with. Different API calls obviously have a different response. Although some API calls, such as those which simply return whether the call was successful or not, use the same response.

A valid session must be opened in order to use the API. This ensures that the user is properly authenticated. If an API call is requested without a session, or with an invalid session, the call is simply ignored and an error message is shown to the user.

To open an API session, the following POST request should be used:

http://localhost:35113/api/sessions/start

This call requires the following parameters:

• ServerPort: The port being used by the Altaro Agent. This can be left out if the default 35107 port is being used.
• Username: A username which has access to the machine where Altaro VM Backup is running.
• Password: The password of the above username.
• Domain: The domain of the above username.

There are two equivalent cmdlets. These are StartSessionPasswordHidden.ps1 and StartSessionPasswordShown.ps1. The main difference between these two is that the former prompts the user for the password, while the latter accepts the password as an argument. This means that the former is more secure, but the latter can be easily automated. As it has been mentioned previously, usages for these cmdlets can be accessed using the –help suffix. When the credentials are valid and the call is successful, the response will contain a Session Token. The Session Token is a GUID and must then be used in all the subsequent API calls. This way, there is no need to enter the credentials for every API call; the Session Token is quoted instead, which is much easier.

The API provides two POST requests which enable the user to close sessions. The first one closes only one particular session, while the second one closes all sessions. The second one is a fallback should the user forgets his or her Session Token.

To close a session with a specific Session Token, the following POST request should be used (my_session_token should be changed with the appropriate Session Token GUID):

http://localhost:35113/api/sessions/end/my_session_token

To close all the sessions which are currently open, the following POST request should be used:

http://localhost:35113/api/sessions/end

The equivalent cmdlets are EndSession.ps1 and EndAllSessions.ps1 respectively. Their usage is straightforward. The former should be called with the Session Token as its single argument, while the latter should simply be called without any arguments.

The UI and API cannot be used concurrently. This means that the API will fail to open a session if there is already an opened UI session. Conversely, the UI will fail to log the user in if there is an open API session. This restriction has been enforced to ensure data integrity, since when these are both of these services running concurrently by different users, a situation might arise when something is being updated in the UI by one user, while the same thing is being accessed from the API from another user, or vice-versa. This would lead to inconsistent data and hence, only one service should be used at any given moment.

A virtual machine can be identified in two different ways. The first type is through a GUID which is created by Altaro VM Backup, while the second type is through the GUID which the Hypervisor assigns to the Virtual Machine.

The Altaro Virtual Machine Reference is set whenever a Virtual Machine is configured in Altaro VM Backup. Such a GUID will change if the Virtual Machine is deleted from the Altaro VM Backup configured and then re-configured again. Conversely, the Hypervisor UUID is always available since it is not something which is set by Altaro VM Backup.

The Altaro Virtual Machine Reference is important because it ensures uniqueness of a Virtual Machine whenever it is configured. The Hypervisor UUID does not ensure uniqueness, most notably when cloning a Virtual Machine, the UUID will be the same. This is the reason why the Altaro Virtual Machine GUID is used whenever possible. The Hypervisor UUID is mainly required when adding a Virtual Machine to the Altaro VM Backup configuration. From then onwards, the Altaro Virtual Machine Reference is used.

Another important distinction is between the Altaro Host ID and the Altaro Hypervisor Reference.

The AltaroHypervisorRef is a GUID assigned to either:

• each standalone Hyper-V or VMware host added to the Altaro VM Backup configuration
  or
• each Hyper-V Cluster or VMware vCenter added to the Altaro VM Backup configuration.

Less frequently used is the AltaroHostID which is a GUID assigned to each Hyper-V or VMware host within the Altaro VM Backup configuration whether it is part of a cluster or not. This is used when choosing which specific host to restore a VM to, particularly when restoring a VM to an unconfigured host.