A common question around Veeam Backup for Office 365 (VBO) is about automation and more specific the RESTful API. Since I created an example self-service web portal since VBO 1.5 came out, I’ve had numerous meetings around this topic.

Something which always comes back are questions related to “how do I do X” or “how do I create X”? While it’s easy to explain how it works, I decided to start a blog post series on the use of the RESTful API within VBO. I may even extend this to Veeam Availability Console, Veeam Availability Orchestrator,…

The goal here is to get you started with some common workflows on how to do certain things such as create an organization, a backup job, perform restores and perform auditing. If you want to know on how to design and integrate web-based portals, I suggest you check out Udemy which has great topics on web design (and for example my tool of use is Bootstrap).

Working with RESTful API

Before you can actually start doing something with the RESTful API within VBO, it needs to be enabled from the interface as explained in the user guide. Once this has been done, you can now log on via a client. There are several options available:

• POSTman
• RESTclient (Firefox plugin)

VBO comes with a Swagger client built in which is, by default, available via the RESTful API web service port 4443 (http://<IP>:4443). We will leverage this for the workflow purposes later on.

Getting started: logging in

Before we can actually create, modify, delete or even restore anything, we will need to authenticate against the API. This is exactly the same as using the VBO console and performing a login.

On the Swagger page, we can find the Auth option at the bottom. This will allow us to get a bearer token which we later can use to perform actions against the API service.

We can login via 2 methods:

• VBO server administrator: this is the Windows username and password (for example VBO\Administrator)
• Tenant administrator: this is the username and password leveraged when adding an organization (veeam@somedomain.onmicrosoft.com)

Based upon the method, specific API calls will be available:

• A VBO server administrator will have full permission to all API calls and will be able to create backup jobs, repositories, proxies, organizations,… as well as full restore options and insight into backup and restore logs.
• A tenant administrator will have a restricted scope on the API calls and will only be able to perform restores within their organization.

Before we can actually leverage the API and create things, we will need to log in as a VBO server administrator. Fill in the VBO Windows server administrator and password and hit the “Try it out!” button which will result in a JSON response. You’ll notice this JSON contains 2 different tokens.

• access_token: This token is used to authenticate against the API by leveraging “bearer <access_token>”
• refresh_token: By default after 3600 seconds the access_token will expire, use the refresh_token to continue your session and request a new access_token.

Bearer access token?

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be read as “give access to the bearer of this token.” Every time you make a request to a protected API call this token has to be leveraged (for example getting a list of organizations).

Performing the first login

Now we got our token, we can get started and authenticate. Copy the access_token and go back to the top of the page. You’ll notice a field where you can fill in the api_key by filling in “bearer <access_token>‘. Based on your browsers choice this may already be filled in (this is for example supported in Mozilla Firefox and Google Chrome).

Once filled in, we can hit “Explore” and we’ll get access to all the API calls. From now on everything we will perform on the page is automatically taken care of as we are authenticated.

Understanding the HTTP mechanics

API calls available in VBO leverage the HTTP mechanic. Use HTTP methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests. HTTP requests are based upon the following

• GET: Get the information wanted, for example, an overview on backup repositories
• POST: Used to create new entries, for example, create a new repository.
• PUT: Used to update existing entries, for example, change repository settings.
• DELETE: Used for deleting entries, for example, remove a repository.

For more information on this, have a look at Understanding REST.

Performing our first authenticated request

To finalize the first part of this series, let’s take a look at the response when we request the information about our VBO installation such as our default backup proxy and repository.

Scrolling down on the Swagger page, there is a section dedicated to backup proxies available.

By clicking “Try it out!“, we’ll get an overview on the default proxy in a JSON format (this is the default response content type however this can be modified via the dropdown if you prefer XML output).

The same is possible about backup repositories which can be found at the top of the page under the BackupRepository section.

And here we can get the repository information by clicking the “Try it out!” button and we’ll get an overview in a JSON format.

What’s next?

In the next part, we will dig deeper on how to work via the RESTful API and go over some easy workflows on how to create a new proxy and repository as well as the next part where we will add an organization and explore the creation of a backup job.