Recently I’ve been trying to get to grips with RESTful API on a couple of solutions I use at work, and as a relative newcomer to the whole world of RESTful APIs, I was looking for an simple/easy way to query systems and view the responses. One of my colleagues, Matt Thompson, pointed me in the direction of Postman www.getpostman.com
Postman is a popular REST client, with an intuitive user interface that allows users to send requests, save responses, add tests and create workflows
You can download your flavour of app, in my case Windows x64, from https://www.getpostman.com/
Installation is extremely straight forward, with no options to change/set, so a simple ‘next, next, finish’
Veeam Enterprise Manager
One of the applications I am interested in using RESTful APIs with is Veeam Backup and Replication (VBR). Veeam does have some excellent documentation around this:-
The requirements for using the Veeam RESTful API is an Enterprise Manager installation, as this acts as a kind of ‘proxy’ for the API requests.
It should be pointed out that installing Enterprise Manager is very straight forward, is included in the installation ISO of VBR and is covered by your existing VBR license. I’m not going to cover the installation and configuration of Enterprise Manager in this post, hoping to do so in a separate blog post.
RESTful API authentication
Before you can make API calls you will need to authenticate your session. Veeam operates a 2 step authentication method when using the Veeam Backup Enterprise Manager RESTful API :-
- The user/client must log on to Veeam Backup Enterprise Manager with a valid username and password. These credentials will have been set previously on the Veeam Backup Enterprise Manager portal.
- Using the credentials, the client then obtains an authorization token that must be used while making all API calls during the current logon session.
Using Postman GET to obtain logon session
- In the Postman dashboard, ensure you have set the action to ‘POST‘ and then enter the following details in the ‘Enter request URL‘ bar
(the address can be either IP address or FQDN, in my examples I’m using IP address)
- Now click on the ‘Authorization‘ tab, and from the ‘Type’ drop down box select ‘Basic Auth‘
- Enter the credentials you use to access the Veeam Backup Enterprise Manager console and click ‘Update Request‘
The Veeam RESTful API looks for base64 encoded username and password and thankfully Postman will add the correct encoding then add the relevant header. If you click on the ‘Headers‘ section, then you will see the relevant header format.
- Click on ‘Send‘ and if your session successfully authenticates you should see a similar response as follows :-
This verifies that the credentials used to access Veeam Backup Enterprise Manager are valid.
Using Postman POST to obtain logon session authorization token
- In the list of results on the previous screen, you can click on the link http://<address_of_your_Enterprise_Manager>:9399/api/sessionMngr/?v=latest
- This will open a new tab within Postman. Change the action to ‘POST‘ and set the Authorization to ‘Basic Auth‘. Re-enter the credentials for the Veeam Backup Enterprise Manager portal and click ‘Send‘
- If successful you should receive back a list of the all the valid API sections
- The authorization token can be found in the ‘Headers‘ section in the body of the results. Click on ‘Headers‘ section and look for the X-RestSvcSessionId
Any subsequent API calls made by the client must include this session id contained within the header. Note this value for later use.
Adding a header
- Once you have formed your request in the bar, click on ‘Headers‘
- Click on the ‘New Key‘ line. NB if you set Basic Auth you will see the existing entry for the Authorization header.
- Enter ‘X-RestSvcSessionId‘ as the new key and the value recorded from the previous steps
- Click send and you’re set to go.
Example of making API call and information
So now we can make API calls to our Veeam Backup Enterprise Manager, what kind of information can we retrieve?
Well we can retrieve a summary overview of the Veeam Backup infrastructure components and jobs using the call:-
The hope now is that I can leverage this information into a useful dashboard, possibly using Grafana or something similar.
As a total newbie to RESTful API , I found using Postman very easy to use and extremely helpful at providing a relatively simple way to test API queries and view the results.